@wise/wds-codemods 0.0.1-experimental-4bee5c0 → 0.0.1-experimental-b974fa6

package/DEVELOPER.md

@@ -1,783 +0,0 @@
-# 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.