@wise/wds-codemods 0.0.1-experimental-82259a8 → 0.0.1-experimental-0d8d466

package/.changeset/quick-mails-joke.md

@@ -0,0 +1,128 @@
+---
+'@wise/wds-codemods': major
+---
+
+# 🎉 @wise/wds-codemods@1.0.0 - Initial Release
+
+Welcome to the first major release of WDS Codemods! This comprehensive toolkit provides automated migration support for Wise Design System components, making it easy to upgrade your codebase to the latest component versions.
+
+## ✨ Core Features
+
+### 🔧 Transform Engine
+
+- **Interactive CLI**: Choose transforms and configure options with an intuitive command-line interface
+- **Dry Run Mode**: Preview changes before applying them to your codebase
+- **Monorepo Support**: Built-in support for monorepo package structures with automatic package detection
+- **Smart Package Detection**: Automatically detects package versions in both `package.json` dependencies and `node_modules`
+- **Comprehensive Reporting**: Generates detailed reports for manual review items that require developer attention
+
+### 🎯 Button Component Transform
+
+- **ActionButton Migration**: Automatically converts deprecated `ActionButton` components to modern `Button` with `v2` prop
+- **Legacy Prop Migration**: Transforms legacy props (`priority`, `size`, `type`, `htmlType`, `sentiment`) to new API
+- **Enum Value Conversion**: Converts enum values (e.g., `Priority.PRIMARY`, `Size.LARGE`) to string literals
+- **Icon Integration**: Intelligently processes icon children and converts them to `addonStart`/`addonEnd` props
+- **Link Button Handling**: Properly migrates `as="a"` usage with automatic `href` management
+- **Smart Size Mapping**: Maps legacy size values to new design tokens (`xs`, `sm`, `md`, `lg`, `xl`)
+
+### 🛡️ Robust Validation & Safety
+
+- **Package Version Validation**: Ensures transforms only run when target packages are present and meet version requirements
+- **TypeScript & JSX Support**: Full support for TypeScript and JSX syntax parsing
+- **Expression Analysis**: Handles complex expressions, conditionals, and dynamic values with appropriate fallbacks
+- **Gitignore Integration**: Respects `.gitignore` patterns to avoid processing unnecessary files
+- **Caching System**: Intelligent caching for package version checks to improve performance
+
+### 📊 Advanced Reporting
+
+- **Manual Review Detection**: Identifies code patterns that require human attention
+- **Line-by-Line Reporting**: Precise location reporting for manual review items
+- **Issue Classification**: Categorizes issues by type (deprecated props, unsupported values, ambiguous expressions)
+- **Batch Processing**: Handles multiple files and provides comprehensive summary reports
+
+## 🚀 Usage Examples
+
+### Basic Usage
+
+```bash
+npx @wise/wds-codemods
+```
+
+### Advanced Usage
+
+```bash
+# Run specific transform on a directory
+npx @wise/wds-codemods button ./src --dry
+
+# Target monorepo packages
+npx @wise/wds-codemods button ./packages --monorepo
+
+# Custom ignore patterns
+npx @wise/wds-codemods button ./src --ignore-pattern "**/*.test.tsx,**/stories/**"
+```
+
+## 📋 Supported Transforms
+
+### Button Transform (`button`)
+
+Migrates Button and ActionButton components from `@transferwise/components` v46.5.0+
+
+**Transformations include:**
+
+- ✅ `ActionButton` → `Button` with `v2` prop
+- ✅ Legacy prop migrations (`priority`, `size`, `type`, etc.)
+- ✅ Enum value conversions
+- ✅ Icon children processing
+- ✅ Link button handling (`as="a"` → proper href management)
+- ✅ Sentiment mapping (`type="negative"` → `sentiment="negative"`)
+
+## 🏗️ Architecture Highlights
+
+### Modular Design
+
+- **Transform System**: Extensible architecture for adding new component transforms
+- **Helper Utilities**: Reusable utilities for JSX manipulation, reporting, and validation
+- **Package Detection**: Multi-strategy package version detection (dependencies + node_modules)
+- **Test Infrastructure**: Comprehensive testing utilities for transform development
+
+### Developer Experience
+
+- **Type Safety**: Full TypeScript support with proper type definitions
+- **Error Handling**: Graceful error handling with helpful error messages
+- **Debug Support**: Extensive debug logging for troubleshooting
+- **Extensible**: Easy to add new transforms and extend existing functionality
+
+## 🧪 Quality Assurance
+
+This release includes:
+
+- ✅ **100% Test Coverage** for core utilities and transforms
+- ✅ **End-to-End Testing** with real-world code examples
+- ✅ **Edge Case Handling** for complex expressions and unusual patterns
+- ✅ **Performance Optimization** with intelligent caching and batching
+- ✅ **Memory Management** for large codebases
+
+## 🔮 What's Next?
+
+This foundation enables:
+
+- 🎯 Additional component transforms (Forms, Navigation, etc.)
+- 🚀 Enhanced reporting and analytics
+- 🔧 IDE integrations and tooling
+- 📱 Support for additional package managers
+- 🌍 Community contributions and extensibility
+
+## 🙏 Getting Started
+
+1. Install the package: `npm install -D @wise/wds-codemods`
+2. Run your first transform: `npx @wise/wds-codemods`
+3. Review the generated `codemod-report.txt` for any manual review items
+4. Commit your changes and enjoy your modernized codebase!
+
+---
+
+**Breaking Changes**: This is the initial release, so no breaking changes from previous versions.
+
+**Migration Guide**: See our documentation for detailed migration examples and best practices.
+
+Ready to modernize your Wise Design System components? Let's go! 🚀

package/DEVELOPER.md

@@ -0,0 +1,783 @@
+# Developer Documentation
+
+A comprehensive guide for developing codemods for the Wise Design System.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Transform Structure](#transform-structure)
+- [Helper Functions](#helper-functions)
+- [Testing](#testing)
+- [Package Requirements](#package-requirements)
+- [Manual Review System](#manual-review-system)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (version specified in `.nvmrc`)
+- pnpm 9.15.4
+- Understanding of AST (Abstract Syntax Trees)
+- Basic knowledge of jscodeshift
+
+### Development Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run with coverage
+pnpm test:coverage
+
+# Lint code
+pnpm run lint
+
+# Auto-fix linting issues
+pnpm run lint:fix
+
+# Type checking
+pnpm run lint:types
+
+# Create a changeset for releases
+pnpm run changeset
+
+# Publish releases
+pnpm run release
+```
+
+## Transform Structure
+
+Every transform follows this basic structure:
+
+```typescript
+// src/transforms/my-transform/my-transform.ts
+import type { API, FileInfo, JSCodeshift, Options } from 'jscodeshift';
+import { validatePackageRequirements, createReporter, hasImport } from '../helpers';
+import reportManualReview from '../../utils/reportManualReview';
+
+export const parser = 'tsx'; // Always use tsx for TypeScript + JSX support
+export const packageRequirements = [{ name: '@transferwise/components', version: '>=46.5.0' }];
+
+const transformer = (file: FileInfo, api: API, options: Options) => {
+  // 1. Validate package requirements
+  if (!validatePackageRequirements(options, packageRequirements)) {
+    return file.source;
+  }
+
+  // 2. Set up jscodeshift and reporter
+  const j: JSCodeshift = api.jscodeshift;
+  const root = j(file.source);
+  const manualReviewIssues: string[] = [];
+  const reporter = createReporter(j, manualReviewIssues);
+
+  // 3. Check for relevant imports
+  const { exists: hasComponentImport } = hasImport(
+    root,
+    '@transferwise/components',
+    'MyComponent',
+    j,
+  );
+
+  if (!hasComponentImport) {
+    return file.source; // No relevant imports, skip file
+  }
+
+  // 4. Perform transformations
+  root.findJSXElements('MyComponent').forEach((path) => {
+    // Transform logic here
+  });
+
+  // 5. Report manual review issues
+  if (manualReviewIssues.length > 0) {
+    manualReviewIssues.forEach(async (issue) => {
+      await reportManualReview(file.path, issue);
+    });
+  }
+
+  return root.toSource();
+};
+
+export default transformer;
+```
+
+## Helper Functions
+
+### Import Management
+
+#### `hasImport(root, moduleName, importName, j)`
+
+Checks if a specific import exists and provides utilities to remove it.
+
+```typescript
+import { hasImport } from '../helpers';
+
+// Check for named import
+const { exists: hasComponentImport, remove: removeComponentImport } = hasImport(
+  root,
+  '@transferwise/components',
+  'MyComponent',
+  j,
+);
+
+// Check for legacy component import with removal capability
+const { exists: hasLegacyImport, remove: removeLegacyImport } = hasImport(
+  root,
+  '@transferwise/components',
+  'LegacyComponent',
+  j,
+);
+
+if (hasComponentImport) {
+  // Transform MyComponent elements
+  root.findJSXElements('MyComponent').forEach(transformComponent);
+}
+
+if (hasLegacyImport) {
+  // Transform LegacyComponent to MyComponent
+  root.findJSXElements('LegacyComponent').forEach(transformLegacyComponent);
+
+  // Remove the LegacyComponent import after transformation
+  removeLegacyImport();
+}
+```
+
+**Returns:**
+
+- `exists: boolean` - Whether the import exists
+- `remove: () => void` - Function to remove the import
+
+### JSX Element Utilities
+
+#### `setNameIfJSXIdentifier(elementName, newName)`
+
+Safely renames JSX elements, only if they are simple identifiers (not member expressions).
+
+```typescript
+import { setNameIfJSXIdentifier } from '../helpers';
+
+root.findJSXElements('LegacyComponent').forEach((path) => {
+  const { openingElement, closingElement } = path.node;
+
+  // Rename opening tag from LegacyComponent to NewComponent
+  openingElement.name = setNameIfJSXIdentifier(openingElement.name, 'NewComponent')!;
+
+  // Rename closing tag if it exists
+  if (closingElement) {
+    closingElement.name = setNameIfJSXIdentifier(closingElement.name, 'NewComponent')!;
+  }
+});
+```
+
+#### `hasAttributeOnElement(openingElement, attributeName)`
+
+Checks if a JSX element has a specific attribute.
+
+```typescript
+import { hasAttributeOnElement } from '../helpers';
+
+root.findJSXElements('MyComponent').forEach((path) => {
+  const { openingElement } = path.node;
+
+  // Skip if already has v2 prop
+  if (hasAttributeOnElement(openingElement, 'v2')) {
+    return;
+  }
+
+  // Add v2 prop
+  addAttributesIfMissing(j, openingElement, [
+    { attribute: j.jsxAttribute(j.jsxIdentifier('v2')), name: 'v2' },
+  ]);
+});
+```
+
+#### `addAttributesIfMissing(j, openingElement, attributes)`
+
+Adds attributes to a JSX element only if they don't already exist.
+
+```typescript
+import { addAttributesIfMissing } from '../helpers';
+
+// Add multiple attributes if missing
+addAttributesIfMissing(j, openingElement, [
+  {
+    attribute: j.jsxAttribute(j.jsxIdentifier('v2')),
+    name: 'v2',
+  },
+  {
+    attribute: j.jsxAttribute(j.jsxIdentifier('variant'), j.literal('primary')),
+    name: 'variant',
+  },
+]);
+```
+
+**Parameters:**
+
+- `j` - jscodeshift instance
+- `openingElement` - JSX opening element
+- `attributes` - Array of `{ attribute: JSXAttribute, name: string }`
+
+### Icon Processing
+
+#### `processIconChildren(j, children, iconImports, openingElement)`
+
+Automatically processes icon children and converts them to appropriate addon props.
+
+```typescript
+import { processIconChildren } from '../helpers';
+
+// First, collect icon imports
+const iconImports = new Set<string>();
+root.find(j.ImportDeclaration, { source: { value: '@transferwise/icons' } }).forEach((path) => {
+  path.node.specifiers?.forEach((specifier) => {
+    if (specifier.local) {
+      const localName = (specifier.local as { name: string }).name;
+      iconImports.add(localName);
+    }
+  });
+});
+
+// Then process icons in components
+root.findJSXElements('MyComponent').forEach((path) => {
+  processIconChildren(j, path.node.children, iconImports, path.node.openingElement);
+});
+```
+
+This function:
+
+- Detects icon components in children
+- Converts them to addon object props: `addonStart={{ type: 'icon', value: <IconComponent /> }}`
+- Removes the icon children from the component
+- Handles complex icon expressions that need manual review
+
+**Example transformation:**
+
+```typescript
+// Before
+<MyComponent>
+  <CheckIcon />
+  Content here
+</MyComponent>
+
+// After
+<MyComponent addonStart={{ type: 'icon', value: <CheckIcon /> }}>
+  Content here
+</MyComponent>
+```
+
+### Reporting System
+
+#### `createReporter(j, issues)`
+
+Creates a reporter instance for collecting manual review issues.
+
+```typescript
+import { createReporter } from '../helpers';
+
+const manualReviewIssues: string[] = [];
+const reporter = createReporter(j, manualReviewIssues);
+
+// The reporter provides many methods for different scenarios
+```
+
+#### Reporter Methods
+
+**Element-level reporting:**
+
+```typescript
+// Report general element issues
+reporter.reportElement(componentElement, 'has complex configuration that needs review');
+
+// Report spread props
+reporter.reportSpreadProps(componentElement);
+
+// Report attribute issues automatically
+reporter.reportAttributeIssues(componentElement);
+```
+
+**Prop-specific reporting:**
+
+```typescript
+// Report specific prop issues
+reporter.reportProp(element, 'variant', 'has unsupported value');
+
+// Report attribute with custom reason
+reporter.reportAttribute(attr, element, 'contains dynamic expression');
+
+// Report unsupported values
+reporter.reportUnsupportedValue(element, 'theme', 'custom-theme');
+
+// Report ambiguous expressions
+reporter.reportAmbiguousExpression(element, 'onClick');
+
+// Report conflicting props and children
+reporter.reportPropWithChildren(element, 'label');
+
+// Report deprecated props
+reporter.reportDeprecatedProp(element, 'legacy', 'use "variant" instead');
+
+// Report missing required props
+reporter.reportMissingRequiredProp(element, 'children');
+
+// Report conflicting props
+reporter.reportConflictingProps(element, ['variant', 'theme']);
+```
+
+**Children-specific reporting:**
+
+```typescript
+// Report ambiguous children (icons, conditional rendering, etc.)
+reporter.reportAmbiguousChildren(element, 'icon');
+```
+
+### Package Validation
+
+#### `validatePackageRequirements(options, packageRequirements)`
+
+Validates that required packages are available before running the transform.
+
+```typescript
+import { validatePackageRequirements } from '../helpers';
+
+export const packageRequirements = [
+  { name: '@transferwise/components', version: '>=46.5.0' },
+  { name: '@transferwise/icons', version: '>=1.0.0' },
+];
+
+const transformer = (file: FileInfo, api: API, options: Options) => {
+  // This will return false if packages aren't found/compatible
+  if (!validatePackageRequirements(options, packageRequirements)) {
+    return file.source; // Skip transformation
+  }
+
+  // Continue with transformation...
+};
+```
+
+## Testing
+
+### Basic Test Setup
+
+```typescript
+// src/transforms/my-transform/__tests__/my-transform.test.ts
+import { createTestTransform } from '../../helpers/createTestTransform';
+import transform from '../my-transform';
+
+// Create test transform with package requirements
+const testTransform = createTestTransform(transform, [
+  { name: '@transferwise/components', version: '46.5.0' },
+]);
+
+describe('my-transform', () => {
+  it('should transform basic component', () => {
+    const input = `
+      import { OldComponent } from '@transferwise/components';
+      
+      <OldComponent prop="value" />
+    `;
+
+    const expected = `
+      import { NewComponent } from '@transferwise/components';
+      
+      <NewComponent newProp="value" />
+    `;
+
+    expect(testTransform({ source: input }).trim()).toBe(expected.trim());
+  });
+});
+```
+
+### Testing with Different Package Scenarios
+
+```typescript
+import {
+  createTestTransform,
+  createTestTransformWithPackage,
+  createTestTransformWithoutPackage,
+} from '../../helpers/createTestTransform';
+
+describe('package requirement scenarios', () => {
+  it('should transform when package is available', () => {
+    const testTransform = createTestTransformWithPackage(
+      transform,
+      '@transferwise/components',
+      '46.5.0',
+    );
+
+    const result = testTransform({ source: input });
+    expect(result).toBe(expectedOutput);
+  });
+
+  it('should skip transformation when package is missing', () => {
+    const testTransform = createTestTransformWithoutPackage(
+      transform,
+      '@transferwise/components',
+      '46.5.0',
+    );
+
+    const result = testTransform({ source: input });
+    expect(result).toBe(input); // Should remain unchanged
+  });
+});
+```
+
+### Testing Manual Review Cases
+
+```typescript
+describe('manual review cases', () => {
+  it('should handle spread props', () => {
+    const input = `<MyComponent {...props} />`;
+    const result = testTransform({ source: input });
+
+    // The transform should still run but flag for manual review
+    expect(result).toContain('v2');
+    // Manual review issues would be captured in a real scenario
+  });
+
+  it('should handle complex expressions', () => {
+    const input = `<MyComponent variant={computeVariant()} />`;
+    const result = testTransform({ source: input });
+
+    // Should preserve the expression but flag for review
+    expect(result).toContain('computeVariant()');
+  });
+});
+```
+
+### Testing Icon Processing
+
+```typescript
+describe('icon processing', () => {
+  it('should convert leading icons to addon props', () => {
+    const input = `
+      import { MyComponent } from '@transferwise/components';
+      import { CheckIcon } from '@transferwise/icons';
+      
+      <MyComponent>
+        <CheckIcon />
+        Content text
+      </MyComponent>
+    `;
+
+    const expected = `
+      import { MyComponent } from '@transferwise/components';
+      import { CheckIcon } from '@transferwise/icons';
+      
+      <MyComponent v2 addonStart={{ type: 'icon', value: <CheckIcon /> }}>
+        Content text
+      </MyComponent>
+    `;
+
+    expect(testTransform({ source: input })).toBe(expected);
+  });
+});
+```
+
+## Package Requirements
+
+### Defining Requirements
+
+```typescript
+export const packageRequirements = [
+  {
+    name: '@transferwise/components',
+    version: '>=46.5.0', // Semantic version range
+  },
+  {
+    name: '@transferwise/icons',
+    version: '^1.0.0', // Caret range
+  },
+  {
+    name: '@transferwise/tokens',
+    version: '~1.5.0', // Tilde range
+  },
+];
+```
+
+### How Package Validation Works
+
+The system checks for packages in this order:
+
+1. **Direct dependencies** - `package.json` files
+2. **Lockfiles** - `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`
+3. **Node modules** - Installed packages in `node_modules/`
+
+For monorepos, it checks across all workspace packages and provides a summary.
+
+## Manual Review System
+
+### When to Use Manual Review
+
+Use manual review reporting when:
+
+- **Spread props** are present: `<MyComponent {...props} />`
+- **Dynamic expressions** can't be safely transformed: `<MyComponent variant={calculateVariant()} />`
+- **Complex children** need human review: `<MyComponent>{condition ? <Icon1 /> : <Icon2 />}</MyComponent>`
+- **Unsupported prop values** are found: `<MyComponent theme="custom" />`
+- **Conflicting props** are present: `<MyComponent label="Click" children="Also click" />`
+
+### Best Practices for Reporting
+
+```typescript
+// ✅ Good - Specific and actionable
+reporter.reportUnsupportedValue(element, 'variant', 'custom');
+// "prop "variant" on <MyComponent> at line 42 has unsupported value "custom""
+
+// ✅ Good - Explains the conflict
+reporter.reportPropWithChildren(element, 'label');
+// "prop "label" on <MyComponent> at line 42 conflicts with children"
+
+// ❌ Avoid - Too vague
+reporter.reportElement(element, 'needs review');
+```
+
+## Best Practices
+
+### Transform Design
+
+1. **Start small** - Begin with simple transformations and gradually add complexity
+2. **Fail safely** - When in doubt, preserve existing code and report for manual review
+3. **Be specific** - Provide clear, actionable manual review messages
+4. **Test edge cases** - Include tests for complex scenarios and error conditions
+
+### Code Organisation
+
+```typescript
+// Group related transformations
+const transformComponent = (path: ASTPath<JSXElement>) => {
+  // Component-specific logic
+};
+
+const transformLegacyComponent = (path: ASTPath<JSXElement>) => {
+  // Legacy component-specific logic
+};
+
+// Main transformer delegates to specific functions
+const transformer = (file: FileInfo, api: API, options: Options) => {
+  // Setup...
+
+  if (hasComponentImport) {
+    root.findJSXElements('MyComponent').forEach(transformComponent);
+  }
+
+  if (hasLegacyImport) {
+    root.findJSXElements('LegacyComponent').forEach(transformLegacyComponent);
+    removeLegacyImport();
+  }
+
+  // Cleanup...
+};
+```
+
+### Error Handling
+
+```typescript
+// Wrap risky operations in try-catch
+openingElement.attributes?.forEach((attr) => {
+  try {
+    if (attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier') {
+      // Safe to access attr.name.name
+      const propName = attr.name.name;
+      // Process attribute...
+    }
+  } catch (error) {
+    reporter.reportAttribute(attr, path, 'could not be processed automatically');
+  }
+});
+```
+
+### Performance Considerations
+
+1. **Early returns** - Skip files without relevant imports
+2. **Efficient queries** - Use specific selectors instead of broad searches
+3. **Minimise DOM traversal** - Cache frequently accessed nodes
+
+```typescript
+// ✅ Good - Early return if no relevant imports
+if (!hasComponentImport && !hasLegacyImport) {
+  return file.source;
+}
+
+// ✅ Good - Specific query
+root.findJSXElements('MyComponent').forEach(transformComponent);
+
+// ❌ Avoid - Broad search
+root.find(j.JSXElement).forEach((path) => {
+  if (
+    path.node.openingElement.name.type === 'JSXIdentifier' &&
+    path.node.openingElement.name.name === 'MyComponent'
+  ) {
+    transformComponent(path);
+  }
+});
+```
+
+## Examples
+
+### Complete Transform Example (Simplified)
+
+```typescript
+// src/transforms/my-component-v2/my-component-v2.ts
+import type { API, FileInfo, JSCodeshift, Options } from 'jscodeshift';
+import reportManualReview from '../../utils/reportManualReview';
+import {
+  addAttributesIfMissing,
+  createReporter,
+  hasAttributeOnElement,
+  hasImport,
+  validatePackageRequirements,
+} from '../helpers';
+
+export const parser = 'tsx';
+export const packageRequirements = [{ name: '@transferwise/components', version: '>=46.5.0' }];
+
+const transformer = (file: FileInfo, api: API, options: Options) => {
+  // 1. Validate package requirements
+  if (!validatePackageRequirements(options, packageRequirements)) {
+    return file.source;
+  }
+
+  // 2. Setup
+  const j: JSCodeshift = api.jscodeshift;
+  const root = j(file.source);
+  const manualReviewIssues: string[] = [];
+  const reporter = createReporter(j, manualReviewIssues);
+
+  // 3. Check for component import
+  const { exists: hasComponentImport } = hasImport(
+    root,
+    '@transferwise/components',
+    'MyComponent',
+    j,
+  );
+
+  if (!hasComponentImport) {
+    return file.source;
+  }
+
+  // 4. Transform components
+  root.findJSXElements('MyComponent').forEach((path) => {
+    const { openingElement } = path.node;
+
+    // Skip if already has v2 prop
+    if (hasAttributeOnElement(openingElement, 'v2')) {
+      return;
+    }
+
+    // Add v2 prop
+    addAttributesIfMissing(j, openingElement, [
+      { attribute: j.jsxAttribute(j.jsxIdentifier('v2')), name: 'v2' },
+    ]);
+
+    // Handle variant prop transformation
+    const variantAttr = openingElement.attributes?.find(
+      (attr) =>
+        attr.type === 'JSXAttribute' &&
+        attr.name.type === 'JSXIdentifier' &&
+        attr.name.name === 'variant',
+    );
+
+    if (
+      variantAttr &&
+      variantAttr.type === 'JSXAttribute' &&
+      variantAttr.value?.type === 'StringLiteral'
+    ) {
+      const oldVariant = variantAttr.value.value;
+      const newVariant =
+        oldVariant === 'accent' ? 'primary' : oldVariant === 'subtle' ? 'secondary' : oldVariant;
+      variantAttr.value.value = newVariant;
+    }
+
+    // Report spread props for manual review
+    if (openingElement.attributes?.some((attr) => attr.type === 'JSXSpreadAttribute')) {
+      reporter.reportSpreadProps(path);
+    }
+  });
+
+  // 5. Report manual review issues
+  if (manualReviewIssues.length > 0) {
+    manualReviewIssues.forEach(async (issue) => {
+      await reportManualReview(file.path, issue);
+    });
+  }
+
+  return root.toSource();
+};
+
+export default transformer;
+```
+
+### Complete Test Example
+
+```typescript
+// src/transforms/my-component-v2/__tests__/my-component-v2.test.ts
+import { createTestTransform } from '../../helpers/createTestTransform';
+import transform from '../my-component-v2';
+
+const testTransform = createTestTransform(transform, [
+  { name: '@transferwise/components', version: '46.5.0' },
+]);
+
+describe('my-component-v2 transform', () => {
+  it('should add v2 prop to MyComponent instances', () => {
+    const input = `
+      import { MyComponent } from '@transferwise/components';
+      
+      <MyComponent variant="accent">Content</MyComponent>
+    `;
+
+    const expected = `
+      import { MyComponent } from '@transferwise/components';
+      
+      <MyComponent v2 variant="primary">Content</MyComponent>
+    `;
+
+    expect(testTransform({ source: input })).toBe(expected);
+  });
+
+  it('should skip components that already have v2 prop', () => {
+    const input = `
+      import { MyComponent } from '@transferwise/components';
+      
+      <MyComponent v2 variant="primary">Already upgraded</MyComponent>
+    `;
+
+    expect(testTransform({ source: input })).toBe(input);
+  });
+
+  it('should skip files without component imports', () => {
+    const input = `
+      import { OtherComponent } from '@transferwise/components';
+      
+      <OtherComponent>Content</OtherComponent>
+    `;
+
+    expect(testTransform({ source: input })).toBe(input);
+  });
+
+  it('should handle spread props', () => {
+    const input = `
+      import { MyComponent } from '@transferwise/components';
+      
+      <MyComponent {...props}>Content</MyComponent>
+    `;
+
+    const result = testTransform({ source: input });
+
+    // Should still add v2 prop but flag for manual review
+    expect(result).toContain('v2');
+  });
+});
+```
+
+This comprehensive guide should help developers understand how to create effective, robust, and well-tested codemods for the Wise Design System.

package/README.md

@@ -12,15 +12,19 @@
 - [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)
 
 ## 👨‍💻 The Repository
 
 The project provides a flexible CLI interface that allows you to run codemods either interactively
-via prompts or directly through command-line arguments.
+via prompts or directly through command-line arguments. It includes intelligent package validation,
+monorepo support, and comprehensive reporting for manual review cases.
 
 ## 🚀 Getting started
 
@@ -30,7 +34,27 @@ 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
@@ -53,36 +77,83 @@ You will be prompted to:
 - 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 <transformFile> <targetPath> [--dry] [--print]
+wds-codemods <transform> <targetPath> [--dry] [--print] [--monorepo]
 ```
 
-Or using `npx`:
+Or using package runners:
 
 ```bash
-npx wds-codemods <transformFile> <targetPath> [--dry] [--print]
+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.
+- `--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). Multiple patterns can be comma separated.
+- `--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.
 
-Example:
+Examples:
 
 ```bash
-wds-codemods simple-rename ./src --dry
+# 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
 ```
 
+## 🔧 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
@@ -126,9 +197,18 @@ standalone TypeScript file exporting a default function that follows the [jscode
 ### Example: Simple Rename Transform
 
 ```ts
-import type { API, FileInfo } from 'jscodeshift';
+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 transformer = (file: FileInfo, api: API) => {
   const j = api.jscodeshift;
   const root = j(file.source);
 
@@ -144,15 +224,68 @@ export default transformer;
 ### Adding a New Transform
 
 1. Create a new `.ts` file in `src/transforms/your-transform-name/`.
-2. Export a default function following the jscodeshift transformer signature.
-3. Write unit tests for your transform using the `createTestTransform` utility found in `src/utils/createTestTransform.ts`.
-4. Build the project to compile your transform.
-5. Run the codemod runner and select your new transform.
+2. Export a `packageRequirements` array defining required dependencies.
+3. Export a default function following the jscodeshift transformer signature.
+4. Use helper utilities from `src/transforms/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 export a `packageRequirements` array that specifies which packages and versions are required:
+
+```ts
+export const packageRequirements = [
+  { name: '@wise/components', version: '>=2.0.0' },
+  { name: '@wise/icons', version: '>=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/transforms/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/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:
@@ -163,6 +296,12 @@ 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
@@ -177,6 +316,10 @@ This project uses jscodeshift as the core engine to perform code transformations
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wise/wds-codemods",
-  "version": "0.0.1-experimental-82259a8",
+  "version": "0.0.1-experimental-0d8d466",
   "license": "UNLICENSED",
   "author": "Wise Payments Ltd.",
   "type": "module",