OpenParable
Skip to content
← Back to skills

Java Ast Refactoring

Development
java-ast-refactoring

Java Ast Refactoring is an Agent Skill for development published in the google/nomulus repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

AST-aware Java refactoring using OpenRewrite. Use when asked to structurally refactor Java code, change class names, change method signatures/overloads, replace builder patterns, modify annotations, or perform cross-file structural replacements. Note: Renaming fields or local variables/parameters is not supported natively via simple YAML recipes in the standard openrewrite modules.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/google/nomulus/blob/HEAD/.gemini/skills/java-ast-refactoring/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/java-ast-refactoring, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

AST-Aware Java Refactoring

This skill uses OpenRewrite to perform Abstract Syntax Tree (AST) based refactoring on Java codebases. This is highly preferred over text-based regex or python scripts because it understands Java semantics, correctly updates imports, and preserves formatting.

Parameter and Field Renaming (Last Resort)

Because OpenRewrite's YAML recipes do not natively support simple variable or field renaming, a custom script is provided:

python3 .gemini/skills/java-ast-refactoring/scripts/safe_rename.py <filepath> <old_name> <new_name>

CRITICAL: Running this python script is a LAST RESORT. It is a regex-based token replacement that ignores strings and comments, but it lacks true AST understanding. ALWAYS prefer using OpenRewrite recipes (rewrite.yml) for structural changes like renaming classes, methods, or moving targets, as OpenRewrite correctly handles imports, types, and cross-file references safely.

Usage

  1. Create a rewrite.yml recipe file in the workspace root. Refer to .gemini/skills/java-ast-refactoring/references/rewrite_recipes.md for syntax.
  2. Execute the script:
./.gemini/skills/java-ast-refactoring/scripts/run_rewrite.sh rewrite.yml
  1. The script will safely apply the AST transformations and then automatically run ./gradlew spotlessApply and ./gradlew javaIncrementalFormatApply on the modified files to automatically fix any Checkstyle line-length and import ordering issues caused by longer/shorter identifiers. Verify the output using git diff.
  2. MANDATORY: Always run ./gradlew build -x test (or the equivalent compile task) after running OpenRewrite to ensure no compilation errors were introduced.

Known Limitations & Troubleshooting

  • Static Imports Dropped on Class Rename: When using ChangeType to rename a class, OpenRewrite may sometimes drop static imports for fields/constants belonging to the old class instead of updating them to the new class. If compilation fails due to "cannot find symbol" for a constant after a class rename, manually restore the static import (e.g., import static com.new.ClassName.CONSTANT;).
  • Continuous Improvement: If any new issues or edge cases are found while running the refactoring (e.g., build failures, formatting issues, or missed transformations), you MUST proactively ask the user if you should permanently update this skill file (SKILL.md) and its accompanying scripts (scripts/run_rewrite.sh, scripts/safe_rename.py) to fix the issue for future use. Do not wait for the user to prompt you to fix the infrastructure.