Migrate from Immer to Mutative for immutable LST updates (#450)

* Migrate from Immer to Mutative for immutable LST updates

- Replace `immer` with `mutative` dependency in setup docs and npm install commands
- Change all `produce()` calls to `create()` from mutative across examples and templates
- Update recipe registration to use `RecipeMarketplace` with `CategoryDescriptor` category paths instead of `RecipeRegistry`
- Add documentation for category hierarchy patterns with nested descriptors
- Maintain `produceAsync()` from `@openrewrite/rewrite` for async operations

* Adjust for RecipeMarketplace

Author: knutwannheden

docs/authoring-recipes/javascript-recipe-development-environment.md

@@ -76,8 +76,8 @@ Next, let's install the core OpenRewrite framework and the required dependencies
 # Core OpenRewrite framework - should be compatible with your Moderne CLI version
 npm install @openrewrite/rewrite
 
-# Immer is required for modifying LSTs immutably
-npm install immer
+# Mutative is required for modifying LSTs immutably
+npm install mutative
 
 # Development dependencies for testing and building
 npm install --save-dev typescript jest @jest/globals ts-jest rimraf
@@ -192,21 +192,24 @@ Add the following build and test scripts to your `package.json`:
 In order for the Moderne CLI to discover your recipes, you need to export them. To do so, create a `src/index.ts` file that looks like:
 
 ```typescript title="src/index.ts"
-import { RecipeRegistry } from '@openrewrite/rewrite';
+import { RecipeMarketplace, CategoryDescriptor } from '@openrewrite/rewrite';
 import { MyRecipe } from './my-recipe';
 
 export { MyRecipe } from './my-recipe';
 // Export additional recipes here
 
+// Define category hierarchy for your recipes
+export const MyPackage: CategoryDescriptor[] = [{displayName: "My Recipes"}];
+
 /**
  * Activates and registers all recipes in this module.
  * This function is called by OpenRewrite to discover available recipes.
  *
- * @param registry The recipe registry to register recipes with
+ * @param marketplace The recipe marketplace to install recipes into
  */
-export function activate(registry: RecipeRegistry) {
-    registry.register(MyRecipe);
-    // Register additional recipes here
+export async function activate(marketplace: RecipeMarketplace): Promise<void> {
+    await marketplace.install(MyRecipe, MyPackage);
+    // Install additional recipes here
 }
 ```
 

docs/authoring-recipes/writing-a-javascript-refactoring-recipe.md

@@ -79,19 +79,22 @@ Note that this recipe doesn't _do_ anything, yet - we'll get to that later.
 Next, let's ensure your recipe can be discovered and run by the [Moderne CLI](https://docs.moderne.io/user-documentation/moderne-cli/getting-started/cli-intro). Update your `src/index.ts` to export and register the recipe:
 
 ```typescript title="index.ts"
-import { RecipeRegistry } from '@openrewrite/rewrite';
+import { RecipeMarketplace, CategoryDescriptor } from '@openrewrite/rewrite';
 import { MigrateUtilFunctions } from './migrate-util-functions';
 
 export { MigrateUtilFunctions } from './migrate-util-functions';
 
+// Define category hierarchy for your recipes
+export const MyPackage: CategoryDescriptor[] = [{displayName: "My Recipes"}];
+
 /**
  * Activates and registers all recipes in this module.
  * This function is called by OpenRewrite to discover available recipes.
  *
- * @param registry The recipe registry to register recipes with
+ * @param marketplace The recipe marketplace to install recipes into
  */
-export function activate(registry: RecipeRegistry) {
-    registry.register(MigrateUtilFunctions);
+export async function activate(marketplace: RecipeMarketplace): Promise<void> {
+    await marketplace.install(MigrateUtilFunctions, MyPackage);
 }
 ```
 

openrewrite-recipe-writer/skills/writing-openrewrite-recipes-js/SKILL.md

@@ -61,7 +61,7 @@ Verification guide:
 
 ```bash
 npm install @openrewrite/rewrite@next  # Latest features
-npm install --save-dev typescript @types/node immer @jest/globals jest
+npm install --save-dev typescript @types/node @jest/globals jest
 ```
 
 ### TypeScript Configuration
@@ -89,8 +89,8 @@ Follow this checklist when creating recipes:
 - [ ] Create visitor extending `JavaScriptVisitor`
 - [ ] Override visit methods for target AST nodes
 - [ ] **For pattern-based transformations:** Use `rewrite()` helper with `tryOn()` method
-- [ ] **For manual AST modifications:** Use `produce()` from `immer` for immutable updates
-- [ ] **For async operations in produce:** Use `produceAsync()` from `@openrewrite/rewrite`
+- [ ] **For manual AST modifications:** Use `create()` from `mutative` for immutable updates
+- [ ] **For async operations:** Use `produceAsync()` from `@openrewrite/rewrite`
 - [ ] Write tests using `RecipeSpec` and `rewriteRun()`
 - [ ] Register recipe in `activate()` function (see [Recipe Registration](#recipe-registration))
 
@@ -390,9 +390,9 @@ if (!isMethodInvocation(node)) {
 // Now TypeScript knows node is J.MethodInvocation
 ```
 
-4. **Use produce() for modifications:**
+4. **Use create() for modifications:**
 ```typescript
-return produce(node, draft => {
+return create(node, draft => {
     draft.name = newName;
 });
 ```
@@ -651,15 +651,17 @@ const x = capture<J.Literal>({
 });
 ```
 
-### Immer produce() issues
+### Mutative create() issues
 ```typescript
+import {create} from "mutative";
+
 // ❌ Wrong - reassigning draft
-return produce(node, draft => {
+return create(node, draft => {
     draft = someOtherNode;  // Won't work
 });
 
 // ✅ Correct - modify properties
-return produce(node, draft => {
+return create(node, draft => {
     draft.name = newName;
 });
 ```
@@ -754,35 +756,61 @@ import {RecipeSpec} from "@openrewrite/rewrite/test";
 import {javascript, typescript, jsx, tsx, npm, packageJson} from "@openrewrite/rewrite/javascript";
 
 // Recipe Registration
-import {RecipeRegistry} from "@openrewrite/rewrite";
+import {RecipeMarketplace, CategoryDescriptor} from "@openrewrite/rewrite";
 ```
 
 ## Recipe Registration
 
-To make recipes discoverable by OpenRewrite, export an `activate()` function from the package entry point (typically `index.ts`). This function receives a `RecipeRegistry` and registers recipe classes with it.
+To make recipes discoverable by OpenRewrite, export an `activate()` function from the package entry point (typically `index.ts`). This function receives a `RecipeMarketplace` and installs recipe classes with a category path.
 
 ### Basic Registration
 
 ```typescript
-import { RecipeRegistry } from '@openrewrite/rewrite';
+import { RecipeMarketplace, CategoryDescriptor } from '@openrewrite/rewrite';
 import { MyRecipe } from './my-recipe';
 import { AnotherRecipe } from './another-recipe';
 
-export async function activate(registry: RecipeRegistry): Promise<void> {
-    registry.register(MyRecipe);
-    registry.register(AnotherRecipe);
+// Define your package's root category
+export const MyPackage: CategoryDescriptor[] = [{displayName: "My Package"}];
+
+// Define subcategories (they extend the parent path)
+export const Search: CategoryDescriptor[] = [...MyPackage, {displayName: "Search"}];
+export const Cleanup: CategoryDescriptor[] = [...MyPackage, {displayName: "Cleanup"}];
+
+export async function activate(marketplace: RecipeMarketplace): Promise<void> {
+    await marketplace.install(MyRecipe, MyPackage);
+    await marketplace.install(AnotherRecipe, Cleanup);
 }
 
 // Also export recipe classes for direct use
 export { MyRecipe } from './my-recipe';
 export { AnotherRecipe } from './another-recipe';
 ```
 
+### Category Paths
+
+Categories are specified as arrays of `CategoryDescriptor` objects, from shallowest to deepest:
+
+```typescript
+// Root category for JavaScript recipes
+export const JavaScript: CategoryDescriptor[] = [{displayName: "JavaScript"}];
+
+// Nested category: JavaScript > Search
+export const Search: CategoryDescriptor[] = [...JavaScript, {displayName: "Search"}];
+
+// Nested category: JavaScript > Migrate > TypeScript
+export const Migrate: CategoryDescriptor[] = [...JavaScript, {displayName: "Migrate"}];
+export const MigrateTypeScript: CategoryDescriptor[] = [...Migrate, {
+    displayName: "TypeScript",
+    description: "Migrate TypeScript-specific patterns"
+}];
+```
+
 ### Important Notes
 
-1. **Pass the class, not an instance**: `registry.register(MyRecipe)` not `registry.register(new MyRecipe())`
+1. **Pass the class, not an instance**: `marketplace.install(MyRecipe, Category)` not `marketplace.install(new MyRecipe(), Category)`
 
-2. **Recipes must be instantiable without arguments**: The registry creates a temporary instance to read the recipe's `name` property. Recipes with required options (no defaults) cannot be registered this way.
+2. **Recipes must be instantiable without arguments**: The marketplace creates a temporary instance to read the recipe's descriptor. Recipes with required options (no defaults) cannot be registered this way.
 
 ```typescript
 // ✅ Can be registered - no required options
@@ -813,13 +841,18 @@ export class RequiredOptionRecipe extends Recipe {
 }
 ```
 
-3. **Async function**: The `activate()` function should be `async` and return `Promise<void>`.
+3. **Async function**: The `activate()` function should be `async` and return `Promise<void>`. Each `install()` call should be awaited.
 
 ### Complete Example
 
 ```typescript
 // src/index.ts
-import { RecipeRegistry } from '@openrewrite/rewrite';
+import { RecipeMarketplace, CategoryDescriptor } from '@openrewrite/rewrite';
+
+// Define category hierarchy
+export const MyLibrary: CategoryDescriptor[] = [{displayName: "My Library"}];
+export const Migrations: CategoryDescriptor[] = [...MyLibrary, {displayName: "Migrations"}];
+export const Search: CategoryDescriptor[] = [...MyLibrary, {displayName: "Search"}];
 
 // Re-export all recipes for direct import
 export { MigrateApiCalls } from './migrate-api-calls';
@@ -834,9 +867,9 @@ import { UpdateImports } from './update-imports';
 /**
  * Register all recipes that can be instantiated without arguments.
  */
-export async function activate(registry: RecipeRegistry): Promise<void> {
-    registry.register(MigrateApiCalls);
-    registry.register(UpdateImports);
+export async function activate(marketplace: RecipeMarketplace): Promise<void> {
+    await marketplace.install(MigrateApiCalls, Migrations);
+    await marketplace.install(UpdateImports, Migrations);
     // FindDeprecatedUsage omitted - requires options
 }
 ```

openrewrite-recipe-writer/skills/writing-openrewrite-recipes-js/assets/template-basic-recipe.ts

@@ -16,7 +16,7 @@
 import {ExecutionContext, Recipe} from "@openrewrite/rewrite";
 import {JavaScriptVisitor} from "@openrewrite/rewrite/javascript";
 import {J} from "@openrewrite/rewrite/java";
-import {produce} from "immer";
+import {create} from "mutative";
 
 /**
  * TODO: Add recipe description
@@ -38,8 +38,8 @@ export class MyRecipe extends Recipe {
                 const visited = await super.visitMethodInvocation(method, ctx) as J.MethodInvocation;
 
                 // TODO: Add transformation logic here
-                // Example: Modify the method invocation using produce
-                // return produce(visited, draft => {
+                // Example: Modify the method invocation using create
+                // return create(visited, draft => {
                 //     // Make changes to draft
                 // });
 

openrewrite-recipe-writer/skills/writing-openrewrite-recipes-js/assets/template-recipe-with-options.ts

@@ -16,7 +16,7 @@
 import {ExecutionContext, Option, Recipe} from "@openrewrite/rewrite";
 import {JavaScriptVisitor} from "@openrewrite/rewrite/javascript";
 import {J} from "@openrewrite/rewrite/java";
-import {produce} from "immer";
+import {create} from "mutative";
 
 /**
  * TODO: Add recipe description
@@ -52,7 +52,7 @@ export class MyConfigurableRecipe extends Recipe {
                 // TODO: Add transformation logic using optionValue
                 // Example:
                 // if (someCondition) {
-                //     return produce(visited, draft => {
+                //     return create(visited, draft => {
                 //         // Use optionValue to make changes
                 //     });
                 // }

openrewrite-recipe-writer/skills/writing-openrewrite-recipes-js/examples/manual-bind-to-arrow-simple.ts

@@ -8,7 +8,7 @@
 import {ExecutionContext, Recipe, TreeVisitor} from "@openrewrite/rewrite";
 import {J, isIdentifier} from "@openrewrite/rewrite/java";
 import {JavaScriptVisitor, JS, capture, pattern, template, raw, rewrite} from "@openrewrite/rewrite/javascript";
-import {produce} from "immer";
+import {create} from "mutative";
 
 export class ManualBindToArrowSimple extends Recipe {
     name = "org.openrewrite.javascript.react.manual-bind-to-arrow-simple";
@@ -71,9 +71,9 @@ class BindingRemovalVisitor extends JavaScriptVisitor<ExecutionContext> {
 
         // Remove binding statements by filtering out indices
         if (indicesToRemove.size > 0) {
-            return produce(method, draft => {
+            return create(method, draft => {
                 if (draft.body) {
-                    draft.body = produce(draft.body, bodyDraft => {
+                    draft.body = create(draft.body, bodyDraft => {
                         bodyDraft.statements = bodyDraft.statements.filter(
                             (_, index) => !indicesToRemove.has(index)
                         );
@@ -228,7 +228,7 @@ class CompleteTransformVisitor extends JavaScriptVisitor<ExecutionContext> {
  * 1. Using pattern().configure() with context and dependencies for type attribution
  * 2. Multi-pass transformation strategy
  * 3. Using ExecutionContext to pass data between visitor passes
- * 4. Handling complex AST transformations with produce()
+ * 4. Handling complex AST transformations with create()
  *
  * Production considerations:
  * - Need to handle 'self' variable cleanup

openrewrite-recipe-writer/skills/writing-openrewrite-recipes-js/examples/manual-bind-to-arrow.ts

@@ -16,7 +16,7 @@
 import {ExecutionContext, Recipe, TreeVisitor} from "@openrewrite/rewrite";
 import {J, Expression, Statement, isIdentifier, isLiteral} from "@openrewrite/rewrite/java";
 import {JavaScriptVisitor, capture, pattern, template, raw} from "@openrewrite/rewrite/javascript";
-import {produce} from "immer";
+import {create} from "mutative";
 
 export class ManualBindToArrow extends Recipe {
     name = "org.openrewrite.javascript.react.manual-bind-to-arrow";
@@ -104,9 +104,9 @@ class ManualBindToArrowVisitor extends JavaScriptVisitor<ExecutionContext> {
 
             // Remove binding statements
             if (statementsToRemove.length > 0) {
-                const newMethod = produce(method, draft => {
+                const newMethod = create(method, draft => {
                     if (draft.body) {
-                        draft.body = produce(draft.body, bodyDraft => {
+                        draft.body = create(draft.body, bodyDraft => {
                             bodyDraft.statements = bodyDraft.statements.filter(
                                 stmt => !statementsToRemove.includes(stmt)
                             );
@@ -140,8 +140,8 @@ class ManualBindToArrowVisitor extends JavaScriptVisitor<ExecutionContext> {
 
         // Now convert marked methods to arrow functions
         if (this.methodsToConvert.size > 0) {
-            result = produce(result, draft => {
-                draft.body = produce(draft.body, bodyDraft => {
+            result = create(result, draft => {
+                draft.body = create(draft.body, bodyDraft => {
                     bodyDraft.statements = bodyDraft.statements.map(stmt => {
                         const stmtElement = stmt.element;
 
@@ -201,9 +201,9 @@ class ManualBindToArrowVisitor extends JavaScriptVisitor<ExecutionContext> {
         // Note: This is a simplified approach; full implementation would need
         // to properly handle async, type annotations, and parameter defaults
 
-        return produce(stmt, draft => {
+        return create(stmt, draft => {
             // Preserve comments from original method
-            draft.element = produce(method, methodDraft => {
+            draft.element = create(method, methodDraft => {
                 // Convert to variable declaration with arrow function
                 // This is a conceptual representation; actual implementation
                 // would use template application
@@ -218,8 +218,8 @@ class ManualBindToArrowVisitor extends JavaScriptVisitor<ExecutionContext> {
      * Remove constructors that only contain super() calls.
      */
     private removeEmptyConstructors(classDecl: J.ClassDeclaration): J.ClassDeclaration {
-        return produce(classDecl, draft => {
-            draft.body = produce(draft.body, bodyDraft => {
+        return create(classDecl, draft => {
+            draft.body = create(draft.body, bodyDraft => {
                 bodyDraft.statements = bodyDraft.statements.filter(stmt => {
                     const stmtElement = stmt.element;