openrewrite

Guidance for implementing and modifying OpenRewrite recipes in the Liftwizard project, based on lessons learned from production experience.

When to Use This Skill

Use this skill when:

• Implementing new OpenRewrite recipes
• Converting existing recipes to use Refaster templates
• Debugging type validation issues in recipes
• Deciding between Refaster and traditional Recipe implementations

For test-related guidance, see the separate openrewrite-test skill.

Refaster vs. Traditional Recipe Implementation

When to Use Refaster Templates

✅ Good Use Cases:

• Always prefer Refaster Templates
• Try to implement with Refaster first always
• Don't switch to traditional recipes unless the user confirms

❌ Poor Use Cases:

• Varargs handling (until OpenRewrite issue #4397 adds @Repeated annotation support)
• Generating method references (they lack proper type information in LST)

Combining Multiple @BeforeTemplate Methods

Rule: Combine multiple @BeforeTemplate methods into one nested class when they produce the same @AfterTemplate output.

Within a single nested class, you can have multiple @BeforeTemplate methods that all share one identical @AfterTemplate. This is useful when semantically different source patterns should transform to the same target pattern:

• Flipped comparison order: size() == 0 vs 0 == size() → isEmpty()
• Different operators with same meaning: size() < 1 vs size() <= 0 → isEmpty()
• Other structures with the same meaning: left == null ? right == null : left.equals(right) vs left == right || (left != null && left.equals(right)) → Objects.equals(left, right)

When to create separate nested classes:

Create separate nested classes when the @AfterTemplate output differs in any way:

• Presence/absence of an optional parameter: assertThat(x).isNotEmpty() vs assertThat(x).as(message).isNotEmpty() → separate classes
• Different method calls: foo(x) vs bar(x) → separate classes
• Different parameter types that happen to look similar but aren't actually the same transformation

Refaster Naming Convention

When creating Refaster templates:

• Main class name: RecipeName (e.g., ECSimplifyNegatedSatisfies)
• Generated class name (used in tests): RecipeNameRecipes (e.g., ECSimplifyNegatedSatisfiesRecipes)
• Update YAML recipe files to reference the generated Recipes class

Type Safety and Validation

Using classpath() vs dependsOn()

Prefer classpath() when possible:

• Add .classpath("eclipse-collections-api") to JavaTemplate builders for real Eclipse Collections types
• Add .classpath("eclipse-collections") for implementation classes if needed
• Almost always works and is better than dependsOn()

Use dependsOn() when necessary:

• Verify class stubs in AssertJ migration tests (eclipse-collections-testutils classpath doesn't work)

Experiment incrementally:

1. Remove one dependsOn() text block
2. Run tests - expect failure (missing type information)
3. Add one classpath() entry to fix
4. Run tests - should pass if real JAR class works
5. Stop when tests fail despite class existing in JAR

Removing typeValidationOptions(TypeValidation.none())

Process:

1. Remove .typeValidationOptions(TypeValidation.none()) line
2. Run test
3. If passes, commit
4. If fails, investigate using OpenRewrite FAQ

Common Fix: Add appropriate classpath() entries to JavaTemplate builders to provide real type information

Fundamental Limitations (cannot remove TypeValidation.none()):

• Refaster-generated method references lack proper type information
• These tests must keep .typeValidationOptions(TypeValidation.none())

Common Implementation Patterns

Predicates.not() and Negation Patterns

Add support for both explicit negation (!method()) and Predicates.not() wrapping:

• !iterable.noneSatisfy(p) → iterable.anySatisfy(p)
• Iterate.noneSatisfy(iterable, Predicates.not(p)) → Iterate.anySatisfy(iterable, p)
• Ensure unused Predicates imports are correctly removed

Comparator Support in Sorted Collections

For sorted collection transformations, add overloads that accept a Comparator:

• TreeSortedSet.newSet(Comparator, Arrays.asList(...)) → SortedSets.mutable.with(Comparator, ...)
• Test with both Comparator.naturalOrder() and Comparator.reverseOrder()
• Create separate arities (1-5) when using Refaster due to varargs limitation

Varargs Handling with Refaster

Until OpenRewrite issue #4397 is resolved:

• Create separate template classes for each arity (typically 0-5)
• Or convert to traditional Recipe using JavaIsoVisitor with dynamic placeholder building
• Document in code that Refaster could be used once @Repeated annotation is supported

Documentation Best Practices

Document Refaster Limitations

When refactoring from traditional Recipe to Refaster, document in class javadoc:

• What context-aware features were lost (e.g., circular transformation prevention)
• Why Refaster cannot handle certain cases
• Reference relevant OpenRewrite issues when applicable

Reference OpenRewrite Issues

• Issue #4397: Lack of @Repeated annotation for varargs support in Refaster
• Include issue numbers in comments for future refactoring opportunities

Key Takeaways

1. Always prefer Refaster templates unless there's a specific limitation
2. Always prefer classpath() over dependsOn() when it works
3. Test type safety by removing TypeValidation.none() where possible
4. Document limitations and trade-offs when converting to Refaster
5. Traditional Recipe implementation is better when you need varargs handling or method reference generation