@wise/wds-codemods 0.0.1 → 1.0.0

package/README.md

@@ -1,13 +1,372 @@
-# wds-codemods
+[![Actions](https://github.com/transferwise/wds-codemods/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/transferwise/wds-codemods/actions)
 
-Owner: design-system-web
+# WDS Codemods
 
-Slack channels: #design-system-web
+> 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.
 
 ## Table of Contents
 
-- [Overview](#overview)
+- [The Repository](#-the-repository)
+- [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)
+- [Notes on Key Tools](#-notes-on-key-tools)
+- [Feedback](#-feedback)
 
-## Overview
+## 👨‍💻 The Repository
 
-Codemods for migrating and upgrading Wise Design System components. Automates transformations with safety checks, reporting, and linting enforcement.
+The project provides a flexible CLI interface that allows you to run codemods either interactively
+via prompts or directly through command-line arguments. It includes intelligent package validation,
+monorepo support, and comprehensive reporting for manual review cases.
+
+## 🚀 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:
+
+### To get started, install the package
+
+```bash
+# Using npm
+npm i -g @wise/wds-codemods
+
+# Using pnpm
+pnpm add -g @wise/wds-codemods
+
+# Using yarn
+yarn global add @wise/wds-codemods
+```
+
+Or, if you prefer, you can run it directly without installing globally:
+
+```bash
+# Using npx
+npx @wise/wds-codemods
+
+# Using pnpm
+pnpm dlx @wise/wds-codemods
+
+# Using yarn
+yarn dlx @wise/wds-codemods
+```
+
+### Using Interactive Prompts
+
+Simply run the codemod runner without any arguments:
+
+```bash
+wds-codemods
+```
+
+Or, if you prefer, you can run it directly using `npx` without installing globally:
+
+```bash
+npx wds-codemods
+```
+
+You will 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).
+
+### Using CLI Arguments
+
+You can also run codemods directly by providing arguments:
+
+```bash
+wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
+```
+
+Or using package runners:
+
+```bash
+npx @wise/wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
+```
+
+## Commands
+
+- `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.
+
+Examples:
+
+```bash
+# Basic transform with dry run
+wds-codemods button ./src --dry
+
+# Transform with pattern exclusions
+wds-codemods button ./src --ignore-pattern="*.test.ts,*.stories.ts"
+
+# Ignore multiple directories and file types
+wds-codemods button ./src --ignore-pattern="**/node_modules/**,**/*.test.ts,**/stories/**"
+
+# Ignore specific directories
+wds-codemods button ./src --ignore-pattern="dist/**,build/**,coverage/**"
+
+# Monorepo transformation
+wds-codemods button ./packages --monorepo
+
+# Print output without writing files
+wds-codemods button ./src --print --dry
+```
+
+## 💻 Available Transforms
+
+### Button Transform (`button`)
+
+Migrates `Button` and `ActionButton` components from `@transferwise/components` (v46.5.0+) to the new v2 API.
+
+**Key Features:**
+
+- **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
+
+**Configuration Options:**
+
+During transform execution, you'll be prompted to choose:
+
+- `accentSecondaryMapping`: How accent + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
+- `positiveSecondaryMapping`: How positive + secondary buttons are mapped (`secondary-neutral` recommended or `secondary`)
+
+**Manual Review:**
+
+The transform generates a `codemod-report.txt` file for cases requiring manual attention:
+
+- Spread props (`{...props}`)
+- Dynamic expressions that cannot be statically analyzed
+- Unsupported prop values
+- Ambiguous icon children (conditional rendering, complex expressions)
+
+---
+
+## 🔧 Key Features
+
+### Package Requirements 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
+
+### 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
+
+### Manual Review Reports
+
+- **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
+
+### Intelligent 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
+
+---
+
+## 👨‍💻 Working with the Project Locally
+
+To work with the project locally, follow these steps:
+
+1. **Install dependencies**
+
+```bash
+pnpm install
+```
+
+2. **Build the project**
+
+This compiles the main source and all transform scripts into the `dist` directory:
+
+```bash
+pnpm run build
+```
+
+3. **Run codemods**
+
+After building, you can run the codemods using the instructions above.
+
+### Requirements
+
+This project uses [pnpm](https://pnpm.io/) and [Node](https://nodejs.org/en/).
+Ensure you are using version `9.15.4` for `pnpm`, to install please follow
+the [installation guide](https://pnpm.io/installation).
+
+For node make sure you've set you local to the one found in `.nvmrc`. Use
+[nvm](https://github.com/nvm-sh/nvm) to manage your local development versions.
+
+---
+
+## ⚛️ Writing Codemod Transforms
+
+Codemod transforms are located in the `src/transforms` directory. Each transform is a
+standalone TypeScript file exporting a default function that follows the [jscodeshift](https://github.com/facebook/jscodeshift) transformer API.
+
+### Example: Simple Rename Transform
+
+```ts
+import type { API, FileInfo, Options } from 'jscodeshift';
+import { validatePackageRequirements } from '../helpers';
+
+// Define package requirements for this transform
+export const packageRequirements = [{ name: '@wise/components', version: '>=2.0.0' }];
+
+const transformer = (file: FileInfo, api: API, options: Options) => {
+  // Validate package requirements before running
+  if (!validatePackageRequirements(options, packageRequirements)) {
+    return file.source;
+  }
+
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  // Find all identifiers named 'foo' and rename them to 'bar'
+  root.find(j.Identifier, { name: 'foo' }).replaceWith(() => j.identifier('bar'));
+
+  return root.toSource();
+};
+
+export default transformer;
+```
+
+### Adding a New Transform
+
+1. Create a new `.ts` file in `src/transforms/your-transform-name/`.
+2. Create `config.json` file in the same directory and set an object defining required dependencies as well as the type of the codemod.
+3. Export a default function following the jscodeshift transformer signature.
+4. Use helper utilities from `src/helpers/` for common operations.
+5. Write unit tests for your transform using the `createTestTransform` utility.
+6. Build the project to compile your transform.
+7. Run the codemod runner and select your new transform.
+
+### Package Requirements
+
+Each transform should have `prerequisites` defined in `config.json` that specifies which packages and versions are
+required:
+
+```json
+{
+  "prerequisites": {
+    "@wise/components": ">=2.0.0",
+    "@wise/icons": "^1.0.0"
+  }
+}
+```
+
+The system will automatically validate these requirements before running the transform, supporting:
+
+- Semantic version ranges (`>=`, `^`, `~`, etc.)
+- Multiple package managers (npm, pnpm, yarn)
+- Monorepo structures
+- Comprehensive dependency checking (dependencies, devDependencies, peerDependencies)
+
+### Helper Utilities
+
+The codemod provides several helper utilities in `src/helpers/`:
+
+- **`hasImport`** - Check for and manipulate import statements
+- **`processIconChildren`** - Handle icon component transformations
+- **`createReporter`** - Generate manual review reports with detailed context
+- **`validatePackageRequirements`** - Check package dependencies
+- **JSX Element Utils** - Utilities for manipulating JSX elements and attributes
+- **JSX Reporting Utils** - Standardised reporting for common manual review scenarios
+
+Additional utilities are available in `src/controller/utils/` for common operations like file handling, AST
+manipulation, and reporting. As this project evolves, we encourage contributors to add new utilities that can benefit the broader codemod ecosystem.
+
+#### Writing Unit Tests for Transforms
+
+It is important that all codemod transforms have corresponding unit tests to ensure correctness and prevent regressions. Use the `createTestTransform` utility to simplify writing tests for your transforms. This utility helps set up the testing environment and provides helpers to run your transform against sample input and verify the output.
+
+**Basic test setup:**
+
+```ts
+import { createTestTransform } from '../../../helpers/createTestTransform';
+import transform from '../my-transform';
+
+const testTransform = createTestTransform(transform, [
+  { name: '@wise/components', version: '2.0.0' },
+]);
+
+describe('my-transform', () => {
+  it('should transform component', () => {
+    const input = `<OldComponent prop="value" />`;
+    const expected = `<NewComponent newProp="value" />`;
+
+    expect(testTransform({ source: input })).toBe(expected);
+  });
+});
+```
+
+Example usage of `createTestTransform` can be found in the existing tests under `src/transforms/simple-rename/__tests__/simple-rename.test.ts`.
+
+Make sure to run your tests regularly using:
+
+```bash
+pnpm test
+```
+
+---
+
+## 📚 Developer Documentation
+
+For comprehensive development details, including transform architecture, helper function documentation, testing patterns, and best practices, see our [Developer Documentation](./DEVELOPER.md).
+
+---
+
+## 📝 Notes on Key Tools
+
+### jscodeshift
+
+[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.
+
+### @inquirer/prompts
+
+[@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js/tree/main/packages/prompts) is a modern, promise-based library for interactive command-line prompts.
+
+This project uses @inquirer/prompts to provide a user-friendly interactive experience when running codemods without CLI arguments, allowing you to select transforms and options easily.
+
+### semver
+
+[semver](https://github.com/npm/node-semver) is used for semantic version parsing and comparison when validating package requirements. This ensures accurate dependency checking across different version specification formats.
+
+---
+
+## ✍️ 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).