@wise/wds-codemods 0.0.1-experimental-731cdc7 → 0.0.1-experimental-cbae00f

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.