@wise/wds-codemods 0.0.1-experimental-2eb5228 → 0.0.1-experimental-0d8d466

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