Skip to content

Consolidate LLM guidance into CLAUDE.md #6223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Consolidate LLM guidance into CLAUDE.md #6223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 0 additions & 123 deletions .junie/guidelines.md
View file
Open in desktop

This file was deleted.

125 changes: 123 additions & 2 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,43 @@ OpenRewrite is an automated refactoring ecosystem for source code that eliminate

- **Recipe**: Defines what transformation to perform (`org.openrewrite.Recipe`)
- **LST (Lossless Semantic Tree)**: AST preserving all formatting, comments, and type attribution during transformations
- **TreeVisitor**: Implements how to traverse and modify LSTs (`org.openrewrite.TreeVisitor`)
- **TreeVisitor**: Implements how to traverse and modify LSTs (`org.openrewrite.TreeVisitor`)
- **SourceFile**: Represents parsed source code as an LST (`org.openrewrite.SourceFile`)
- **Markers**: Attach metadata to LST nodes without modifying the tree structure

## General Guidelines

### Code Organization
- Code should be organized into modules based on functionality
- Each module should have a clear responsibility
- Follow the package structure conventions established in the project
- Keep files focused on a single responsibility

### Documentation
- Public APIs should be documented with a brief summary at the type level and method level documentation for interfaces
- Include examples in documentation where appropriate
- Document complex algorithms and non-obvious code
- Keep documentation up-to-date with code changes

### Testing
- Write tests for all new features and bug fixes
- Aim for high test coverage
- Tests should be comprehensive and cover edge cases
- Use appropriate testing frameworks (JUnit for Java, Jest for TypeScript)

### Error Handling
- Handle errors appropriately and provide meaningful error messages
- Use exceptions for exceptional conditions, not for control flow
- Validate inputs and fail fast
- Log errors with appropriate context

### Task Management
- Always check tasks in the task list when they are completed
- Update task lists in `docs/tasks.md` to reflect current progress
- Mark tasks as completed by changing `- [ ]` to `- [x]`
- Keep task lists up-to-date to help track project progress
- Ensure all subtasks are checked before marking a parent task as complete

## Essential Build Commands

```bash
Expand Down Expand Up @@ -83,7 +116,7 @@ OpenRewrite is an automated refactoring ecosystem for source code that eliminate
- **`rewrite-java-8/11/17/21`**: Java version-specific features and compatibility
- **`rewrite-groovy/kotlin/javascript`**: Other JVM and web languages extending the `J` model from `rewrite-java`

### Format Parsers
### Format Parsers
- **`rewrite-maven`**: Maven POM manipulation and dependency management
- **`rewrite-gradle`**: Gradle build script parsing (Groovy/Kotlin DSL)
- **`rewrite-json/yaml/xml/hcl/properties/toml/protobuf`**: Configuration and data formats
Expand Down Expand Up @@ -127,6 +160,8 @@ void myRecipeTest() {
}
```

When testing OpenRewrite parsers or recipes use `RewriteTest` and its `rewriteRun()` methods with "before" and "after" state to indicate what changes are expected and not expected to be made to source files.

### Parser Extensions
New language support for grammars that don't have type attribution require:
1. ANTLR grammar files (`.g4`) in `src/main/antlr/`
Expand All @@ -140,7 +175,93 @@ The project supports selective module loading via `IDE.properties` to improve ID
### Quality Checks
The build enforces license headers on all source files and runs OWASP dependency vulnerability scanning. Always run `./gradlew licenseFormat` before committing code changes.

## Java Guidelines

### Code Style
- Follow standard Java naming conventions
- Classes: PascalCase
- Methods and variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Use 4 spaces for indentation
- Keep lines under 120 characters
- Use meaningful variable and method names

### Java Patterns
- Use Lombok annotations to reduce boilerplate (@Getter, @RequiredArgsConstructor, etc.)
- Use interfaces with default methods where appropriate
- Use @Nullable annotations for null safety
- Use functional programming style with streams and lambdas where it improves readability
- Prefer immutable objects where possible
- Use the Builder pattern for complex object creation
- Use the Visitor pattern for tree traversal and transformation

### Java Best Practices
- Favor composition over inheritance
- Use dependency injection for better testability
- Write small, focused methods
- Avoid mutable state where possible
- Use appropriate data structures for the task
- Follow the principle of least surprise

## TypeScript Guidelines

### Organization
- The Node project root for the TypeScript code is `rewrite-javascript/rewrite`. So when running `npm`, make sure to add `--prefix rewrite-javascript/rewrite` to the command or change into that directory before running the command.
- The TypeScript code represents an implementation of OpenRewrite Java in TypeScript
- The modules directly inside `src`, `src/rpc`, `src/text` roughly correspond to the repo-level Gradle project `rewrite-core`
- The modules in `src/java` correspond to the Java code in the Gradle project `rewrite-java`
- The modules in `src/javascript` correspond to the Java code in the Gradle project `rewrite-javascript`
- The modules in `src/json` correspond to the Java code in the Gradle project `rewrite-json`
- The modules in `src/test` correspond to the Java code in the Gradle project `rewrite-test`
- Specifically, there are a lot of types which have the exact same names and structures in both the Java and the TypeScript code (e.g. `JavaVisitor` or `Markers`).
- A lot of types (specifically those in `tree.ts` and `markers.ts` files) represent data types which need to have matching definitions in Java and TypeScript to support a custom serialization mechanism
- The serialization mechanism is generally referred to as RPC and implemented in `src/rpc` (and inside the Java package `org.openrewrite.rpc` of `rewrite-core`)
- Further, the serialization mechanism is visitor-based and thus for each of the supported languages there is a "sender" and a "receiver" (e.g. `JavaSender` and `JavaReceiver`) which each needs an implementation in both Java and TypeScript and at the same time this must be fully aligned with the corresponding model (e.g. `src/java/tree.ts`)

### Code Style
- Follow standard TypeScript naming conventions
- Classes and interfaces: PascalCase
- Methods, properties, and variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Use 4 spaces for indentation
- Keep lines under 120 characters
- Use meaningful variable and method names

### TypeScript Patterns
- Use TypeScript interfaces and classes for type safety
- Use generics for reusable code
- Use async/await for asynchronous operations (including the visitor which is async)
- Use Immer for immutable state management
- Use the visitor pattern for tree traversal and transformation
- Use optional chaining for null/undefined handling

### TypeScript Best Practices
- Explicitly type function parameters and return values
- Use readonly for immutable properties
- Use union types instead of inheritance where appropriate
- Avoid any type where possible
- Use type guards for runtime type checking
- Use async/await instead of raw promises

## Version Control Guidelines

### Commits
- Write clear, concise commit messages
- Each commit should represent a logical change
- Keep commits focused on a single task
- Reference issue numbers in commit messages where applicable

### Pull Requests
- Write a clear description of the changes
- Include tests for new features and bug fixes
- Ensure all tests pass before submitting
- Address review comments promptly

## Important Conventions

### Nullability Annotations
The project uses JSpecify nullability annotations.

## Conclusion

Following these guidelines will help maintain code quality and consistency across the OpenRewrite project. These guidelines are not exhaustive, and common sense should be applied when making decisions not covered here.