@wise/wds-codemods 1.0.0 → 1.1.0

package/README.md

@@ -3,17 +3,22 @@
 # 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)
+- [Transform Engines](#-transform-engines)
+  - [jscodeshift Transforms](#jscodeshift-transforms)
+  - [AI Transforms](#ai-transforms)
 - [Available Transforms](#-available-transforms)
+  - [Button Transform](./src/transforms/button/README.md)
+  - [ListItem Transform](./src/transforms/list-item/README.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 +31,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 +48,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 +61,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) (jscodeshift engine only)
+4. Choose whether to print transformed output
+5. Configure monorepo detection (auto-detected in most cases)
+6. Answer transform-specific configuration questions (jscodeshift engine 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                                                          |
 
-- `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.
+Only jscodeshift engine supports the following options (.gitignore is always respected with AI Engine):
 
-Examples:
+| Option                | Description                              |
+| --------------------- | ---------------------------------------- |
+| `--dry` / `--dry-run` | Preview changes without writing to files |
+| `--gitignore`         | Respect `.gitignore` files               |
+| `--no-gitignore`      | Ignore `.gitignore` files                |
+
+### Common Examples
 
 ```bash
 # Basic transform with dry run
@@ -125,75 +136,100 @@ wds-codemods button ./packages --monorepo
 wds-codemods button ./src --print --dry
 ```
 
-## 💻 Available Transforms
+## 🔧 Transform Engines
+
+This project supports two types of transform engines, each suited for different transformation needs:
+
+### jscodeshift Engine
+
+**Best for:** Predictable, rule-based transformations with clear input/output mappings.
+
+**How it works:**
+
+- Parses code into an Abstract Syntax Tree (AST)
+- Applies deterministic transformations based on pattern matching
+- Guarantees consistent results across runs
+
+**Features:**
 
-### Button Transform (`button`)
+- Dry-run mode to preview changes without writing files
+- Manual review reports for edge cases
+- Fast execution on large codebases
 
-Migrates `Button` and `ActionButton` components from `@transferwise/components` (v46.5.0+) to the new v2 API.
+**Prerequisites:**
 
-**Key Features:**
+- Package version requirements (validated automatically)
 
-- **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
+**Example transforms:** Button migration
 
-**Configuration Options:**
+### AI Engine
 
-During transform execution, you'll be prompted to choose:
+**Best for:** Complex, context-aware transformations that require understanding intent.
 
-- `accentSecondaryMapping`: How accent + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
-- `positiveSecondaryMapping`: How positive + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
+**How it works:**
 
-**Manual Review:**
+- Uses Claude AI to migrate code based on pregenrated instructions
 
-The transform generates a `codemod-report.txt` file for cases requiring manual attention:
+**Features:**
 
-- Spread props (`{...props}`)
-- Dynamic expressions that cannot be statically analyzed
-- Unsupported prop values
-- Ambiguous icon children (conditional rendering, complex expressions)
+- Handles ambiguous cases that would require manual review in jscodeshift
+
+**Prerequisites:**
+
+- Access to Wise LLM Gateway
+- Claude configured locally
+- VPN connection
+- Package version requirements (validated automatically)
+
+**Example transforms:** ListItem migration
+
+---
+
+## 💻 Available Transforms
+
+- **[Button](./src/transforms/button/README.md)** - Migrates `Button` and `ActionButton` to the new v2 API using jscodeshift
+- **[ListItem](./src/transforms/list-item/README.md)** - Migrates legacy `Option` and `Summary` components to `ListItem` using Claude AI
 
 ---
 
 ## 🔧 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
+
+**jscodeshift engine:**
+
+- 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
+**AI engine:**
 
-- **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
+- Handles complex cases inline during transformation
 
-### 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
 
 ---
 
@@ -353,7 +389,13 @@ For comprehensive development details, including transform architecture, helper
 
 [jscodeshift](https://github.com/facebook/jscodeshift) is a toolkit for running codemods over multiple JavaScript or TypeScript files. It provides an API to parse source code into an Abstract Syntax Tree (AST), manipulate it, and print the transformed code back.
 
-This project uses jscodeshift as the core engine to perform code transformations.
+jscodeshift is one of two engines to perform code transformations.
+
+### @anthropic-ai/claude-agent-sdk
+
+[@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) is Anthropic's SDK for building AI-powered agents with Claude. It provides tools for creating context-aware transformations that can understand code semantics and intent.
+
+Claude Agent SDK is one of two engines to perform code transformations
 
 ### @inquirer/prompts
 
@@ -369,4 +411,4 @@ This project uses @inquirer/prompts to provide a user-friendly interactive exper
 
 ## ✍️ Feedback
 
-Please ask any questions on this project, you can do so by reaching out on Slack. Or contributing to any [active issues](https://transferwise.atlassian.net/jira/software/projects/DS/boards/277/backlog).
+Please ask any questions on this project, you can do so by reaching out on [Slack](https://wise.enterprise.slack.com/archives/CJNBX9CP6) or contributing to any [active issues](https://transferwise.atlassian.net/jira/software/projects/DS/boards/277/backlog).

package/dist/constants-CcE2TmzN.js

@@ -0,0 +1,59 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+//#region src/constants.ts
+const CONSOLE_ICONS = {
+	info: "\x1B[34mℹ\x1B[0m",
+	focus: "\x1B[34m➙\x1B[0m",
+	success: "\x1B[32m✔\x1B[0m",
+	warning: "\x1B[33m⚠\x1B[0m",
+	error: "\x1B[31m✖\x1B[0m",
+	claude: "\x1B[35m💬\x1B[0m"
+};
+
+//#endregion
+Object.defineProperty(exports, 'CONSOLE_ICONS', {
+  enumerable: true,
+  get: function () {
+    return CONSOLE_ICONS;
+  }
+});
+Object.defineProperty(exports, '__commonJSMin', {
+  enumerable: true,
+  get: function () {
+    return __commonJSMin;
+  }
+});
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});
+//# sourceMappingURL=constants-CcE2TmzN.js.map

package/dist/constants-CcE2TmzN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants-CcE2TmzN.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["export const CONSOLE_ICONS = {\n  info: '\\x1b[34mℹ\\x1b[0m', // Blue info icon\n  focus: '\\x1b[34m➙\\x1b[0m', // Blue arrow icon\n  success: '\\x1b[32m✔\\x1b[0m', // Green checkmark\n  warning: '\\x1b[33m⚠\\x1b[0m', // Yellow warning icon\n  error: '\\x1b[31m✖\\x1b[0m', // Red cross icon\n  claude: '\\x1b[35m💬\\x1b[0m', // Speech bubble\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,MAAa,gBAAgB;CAC3B,MAAM;CACN,OAAO;CACP,SAAS;CACT,SAAS;CACT,OAAO;CACP,QAAQ;CACT"}