Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
31 changes: 26 additions & 5 deletions .gemini/skills/java-ast-refactoring/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: java-ast-refactoring
description: "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."
description: "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. Don't use for: formatting-only fixes (use spotlessApply / javaIncrementalFormatApply), non-Java files, or single-line edits that a direct file edit handles safely."
---

# AST-Aware Java Refactoring
Expand All @@ -17,13 +17,34 @@ python3 .gemini/skills/java-ast-refactoring/scripts/safe_rename.py <filepath> <o

## 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:
1. Start from a clean working tree (`git status`) so the refactoring diff is isolated and easy to revert.
2. Create a `rewrite.yml` recipe file in the workspace root. Refer to `.gemini/skills/java-ast-refactoring/references/rewrite_recipes.md` for syntax. The recipe's first `name:` line is the recipe that gets activated.
3. Execute the script from the repository root:
```bash
./.gemini/skills/java-ast-refactoring/scripts/run_rewrite.sh rewrite.yml
```
3. 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`.
4. **MANDATORY:** Always run `./gradlew build -x test` (or the equivalent compile task) after running OpenRewrite to ensure no compilation errors were introduced.
A recipe stored elsewhere is copied to `./rewrite.yml` for the run and removed afterwards; a recipe already at `./rewrite.yml` is used in place and left untouched. Delete your own `./rewrite.yml` before committing.
4. 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.

## Verification (Mandatory)

1. Review the full diff (`git diff --stat` and `git diff`) and confirm every change is intended. Revert unrelated edits.
2. Compile everything after running OpenRewrite to ensure no compilation errors were introduced:
```bash
./gradlew build -x test -x :console-webapp:buildConsoleWebapp
```
3. Run the tests covering the touched code, e.g. `./gradlew :core:standardTest -x :console-webapp:buildConsoleWebapp`.
4. Confirm `git status` shows no stray files (`rewrite.yml`, `rewrite-init.gradle`, or a modified `console-webapp/package-lock.json`).
5. Commit, then run the `pr-polisher` skill (`python3 .gemini/skills/pr-polisher/scripts/check_diff.py`) to catch leftover fully qualified names, unused imports, and other anti-patterns.

## Error Recovery

* **Recipe not activated / "Could not extract 'name:'":** Ensure the recipe has a top-level `name:` line and `type: specs.openrewrite.org/v1beta/recipe`.
* **No changes made:** The `methodPattern` or type name likely does not match. Use fully qualified types, `..` for any parameters, and verify against the method patterns section of `references/rewrite_recipes.md`.
* **Gradle or plugin resolution failure:** Re-run with `--stacktrace`. The init script pins the OpenRewrite plugin version; if it is incompatible with the current Gradle version, update the version in `scripts/run_rewrite.sh`.
* **Formatter failures after the run:** Re-run `./gradlew spotlessApply javaIncrementalFormatApply`, then repeat the compile step.
* **Interrupted run:** Remove leftover `rewrite-init.gradle` (and `./rewrite.yml` if it was a temporary copy), then restart.
* **Bad transformation:** Discard it with `git checkout -- <paths>` (or `git stash`), refine the recipe, and re-run rather than hand-patching the output.

## 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;`).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,15 @@ Updates the class name and automatically updates all imports across the codebase
```

### 7. Change Method Arguments
Reorders or removes arguments based on a target signature. `newArgumentTemplate` uses 0-based indexing.
Removes or reorders arguments at every call site matching `methodPattern`. `argumentIndex` is 0-based. `oldParameterNames` lists the current parameter names in declaration order and `newParameterNames` lists them in the desired order. These recipes rewrite invocations only; update the method declaration itself separately.
```yaml
- org.openrewrite.java.ChangeMethodAccessLevel:
methodPattern: com.google.common.collect.ImmutableList of(..)
newAccessLevel: protected
- org.openrewrite.java.DeleteMethodArgument:
methodPattern: google.registry.util.Foo bar(java.lang.String, int)
argumentIndex: 1
- org.openrewrite.java.ReorderMethodArguments:
methodPattern: google.registry.util.Foo baz(java.lang.String, int)
oldParameterNames: [name, count]
newParameterNames: [count, name]
```

### 8. Add Import
Expand Down
14 changes: 11 additions & 3 deletions .gemini/skills/java-ast-refactoring/scripts/run_rewrite.sh
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,14 @@ allprojects {
}
EOF

# Copy the recipe file to the workspace root temporarily so OpenRewrite finds it
cp "$RECIPE_FILE" ./rewrite.yml
# OpenRewrite reads ./rewrite.yml from the workspace root. Copy the recipe there
# temporarily unless it already is that file (copying a file onto itself fails,
# and deleting it afterwards would destroy the user's recipe).
COPIED_RECIPE=false
if [[ "$RECIPE_FILE" != "$(realpath -m ./rewrite.yml)" ]]; then
cp "$RECIPE_FILE" ./rewrite.yml
COPIED_RECIPE=true
fi

echo "Executing OpenRewrite recipe: $RECIPE_NAME"
./gradlew --init-script "$INIT_SCRIPT" rewriteRun --no-parallel --no-configuration-cache
Expand All @@ -77,4 +83,6 @@ echo "Running code formatters to fix Checkstyle line-length and import ordering.

# Clean up temporary files
rm "$INIT_SCRIPT"
rm ./rewrite.yml
if [[ "$COPIED_RECIPE" == true ]]; then
rm ./rewrite.yml
fi
26 changes: 21 additions & 5 deletions .gemini/skills/pr-polisher/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: pr-polisher
description: Automated pre-flight checklist to polish PRs. Use this before declaring a task or PR complete to automatically verify license headers, commit hygiene, formatting, and codebase mandates.
description: Automated pre-flight checklist to polish PRs. Use this before declaring a task or PR complete to automatically verify license headers, commit hygiene, formatting, and codebase mandates. Don't use for: non-Git or Piper changelists.
---

# PR Polisher
Expand All @@ -22,10 +22,10 @@ This skill is designed to evolve. If a human code reviewer (or presubmit hook) p
## Workflow Execution Steps

1. **Run the Automated Analysis Script**
Execute the packaged Python diff-checker script. This script automatically checks commit messages, working tree status, `package-lock.json` modifications, copyright years on new files, and a litany of anti-patterns using regex (e.g., fully-qualified names, incorrect clock injections, generic exception catching).
Execute the packaged Python diff-checker script from the repository root. This script automatically checks commit messages, working tree status, `package-lock.json` modifications, copyright years on new files, missing tests across all tested modules, the 2-PR database schema split (Flyway scripts must not ship with Java or `db-schema.sql.generated` changes), internal-only links or paths leaking into this public repository, local `upstream/master` freshness, and a litany of anti-patterns using regex (e.g., fully-qualified names, incorrect clock injections, generic exception catching).

```bash
python3 ./pr-polisher/scripts/check_diff.py
python3 .gemini/skills/pr-polisher/scripts/check_diff.py
```

2. **Run Formatting Validation**
Expand Down Expand Up @@ -61,11 +61,27 @@ This skill is designed to evolve. If a human code reviewer (or presubmit hook) p
Re-read your commit message (`git log -1 --pretty=format:%B`). Compare it directly against the actual diff (`git diff HEAD^`) to verify that it completely and accurately describes ONLY the changes present in the commit.
* If the scope of the PR changed during prompting, you MUST update the commit message to reflect the final state of the code.
* Ensure that the primary purpose of the PR is mentioned first, and that no irrelevant or outdated changes from previous attempts are listed.
* **Commit-message / PR-body parity:** The commit body and the GitHub PR description must BOTH contain the operational justification (why the change is needed) and, for new or changed commands, concrete CLI usage examples. Never leave this context in only one of the two.

7. **Address Errors, Amend, and Re-Run (Iterative Checking)**
7. **Verify `@Action` Reachability**
If the diff adds or modifies a class annotated with `@Action`, confirm it is actually reachable in production:
* It is wired into `core/src/main/java/google/registry/module/RequestComponent.java`.
* Its path appears in `core/src/test/resources/google/registry/module/routing.txt` (update this golden file using the instructions printed by a failing `RequestComponentTest`).
* Scheduled actions have a matching entry in the relevant `core/src/main/java/google/registry/config/files/tasks/cloud-scheduler-tasks-*.xml` files.

8. **Read ALL Existing PR Review Comments (Paginated)**
When an open PR exists, never rely on a single unpaginated `gh api` or `gh pr view` call, which silently truncates and hides inline comments. Fetch all three endpoints with pagination:
```bash
gh api --paginate repos/google/nomulus/pulls/<n>/comments --jq '.[] | {path, line, user: .user.login, body}'
gh api --paginate repos/google/nomulus/issues/<n>/comments --jq '.[] | {user: .user.login, body}'
gh api --paginate repos/google/nomulus/pulls/<n>/reviews --jq '.[] | {user: .user.login, state, body}'
```
Confirm every comment is addressed (or explicitly replied to) before declaring the PR polished.

9. **Address Errors, Amend, and Re-Run (Iterative Checking)**
If any script throws an error, if scope was reduced, if the commit message was inaccurate, or if formatting changes were applied, you must stage those fixes and amend your commit:
```bash
git add -u
git commit --amend # Or git commit --amend --no-edit if only files changed
```
**CRITICAL:** You must loop back to Step 1 and run `python3 ./pr-polisher/scripts/check_diff.py` again. Continue this loop of checking and amending until the script definitively returns `0 ERRORS`, the build/presubmits pass, and the working directory is perfectly clean. Do not assume your fixes worked without re-running the check.
**CRITICAL:** You must loop back to Step 1 and run `python3 .gemini/skills/pr-polisher/scripts/check_diff.py` again. Continue this loop of checking and amending until the script definitively returns `0 ERRORS`, the build/presubmits pass, and the working directory is perfectly clean. Do not assume your fixes worked without re-running the check.
125 changes: 114 additions & 11 deletions .gemini/skills/pr-polisher/scripts/check_diff.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import sys
import datetime
import os
import time

# Color codes
RED = "\033[91m"
Expand All @@ -28,6 +29,27 @@
errors_found = 0
warnings_found = 0

SCRIPT_PATH = ".gemini/skills/pr-polisher/scripts/check_diff.py"

# Modules whose src/main Java changes should be accompanied by test changes.
TESTED_MODULES = (
"common", "core", "db", "networking", "prober", "proxy", "release", "util")

FLYWAY_SCRIPT_PATTERN = re.compile(r'^db/src/main/resources/sql/flyway/V[^/]*\.sql$')
JPA_ENTITY_PATTERN = re.compile(r'^\s*@(Entity|Embeddable|MappedSuperclass)\b', re.MULTILINE)

# Internal-only references that must never land in this public repository.
# Buganizer references (b/123, http://b/123) are allowed and do not match.
INTERNAL_LEAK_PATTERNS = (
(re.compile(r'corp\.google\.com'), "internal corp hostname"),
(re.compile(r'/google/src/'), "internal source path"),
(re.compile(r'//depot/google3'), "internal depot path"),
(re.compile(r'(?:\bhttps?://|(?<![\w./-]))go/[A-Za-z0-9_-]'), "internal go/ shortlink"),
)

# Warn when the local upstream/master tip is older than this many hours.
UPSTREAM_MAX_AGE_HOURS = 24

def log_error(msg):
global errors_found
errors_found += 1
Expand All @@ -44,6 +66,17 @@ def log_success(msg):
def run_cmd(cmd):
return subprocess.check_output(cmd, shell=True, text=True).strip()

def get_diff_files():
return [f for f in run_cmd("git diff HEAD^ --name-only").split('\n') if f]

def ref_exists(ref):
return subprocess.run(
["git", "rev-parse", "--verify", "--quiet", ref],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
check=False,
).returncode == 0

def check_single_commit():
print("--- Checking Commit Count ---")
try:
Expand Down Expand Up @@ -155,6 +188,21 @@ def check_license_headers():
if files_checked == 0:
log_success("No new files requiring license headers added.")

def check_upstream_freshness():
print("\n--- Checking upstream/master Freshness ---")
upstream_ref = "refs/remotes/upstream/master"
if not ref_exists(upstream_ref):
log_success("No upstream remote configured; skipping freshness check.")
return
commit_time = int(run_cmd(f"git log -1 --format=%ct {upstream_ref}"))
age_hours = (time.time() - commit_time) / 3600
if age_hours > UPSTREAM_MAX_AGE_HOURS:
log_warning(
f"Local upstream/master tip is {age_hours:.0f}h old. Run 'git fetch upstream master'"
" and rebase so the diff is not computed against a stale base.")
else:
log_success("Local upstream/master is fresh.")

def check_formatting():
print("\n--- Checking Project Formatting ---")
try:
Expand Down Expand Up @@ -309,19 +357,71 @@ def check_diff_anti_patterns():
if 'src/test/' in current_file and clock_now_pattern.search(code_line):
log_warning(f"[{current_file}] Prefer using a fixed, static constant Instant over capturing clock.now() in tests to prevent flakiness.")

def check_internal_link_leaks():
print("\n--- Checking for Internal Link and Path Leaks ---")
diff = run_cmd("git diff HEAD^ -U0")
current_file = ""
leaks_found = False

for line in diff.split('\n'):
if line.startswith('+++ '):
current_file = line[6:] if line.startswith('+++ b/') else ""
continue
if not line.startswith('+') or not current_file:
continue
code_line = line[1:]
# Skip this script's own pattern definitions.
if current_file == SCRIPT_PATH and 're.compile(' in code_line:
continue
for pattern, description in INTERNAL_LEAK_PATTERNS:
if pattern.search(code_line):
leaks_found = True
log_error(
f"[{current_file}] Found {description} in an added line. This repository"
f" is public; remove internal references: {code_line.strip()}")

if not leaks_found:
log_success("No internal links or paths found in added lines.")

def is_jpa_entity(path):
if not path.endswith('.java') or '/src/main/' not in path:
return False
try:
with open(path, 'r') as file:
return bool(JPA_ENTITY_PATTERN.search(file.read()))
except FileNotFoundError:
# Deleted files cannot be inspected.
return False

def check_db_schema_split():
print("\n--- Checking Database Schema Changes ---")
diff_files = get_diff_files()
flyway_files = [f for f in diff_files if FLYWAY_SCRIPT_PATTERN.match(f)]
orm_files = [
f for f in diff_files if f.endswith('.java') or f.endswith('db-schema.sql.generated')]
entity_files = [f for f in diff_files if is_jpa_entity(f)]

if flyway_files and orm_files:
log_error(
"Flyway scripts and Java/db-schema.sql.generated changes must be split into two"
" PRs (schema first, then ORM after deployment). See db/README.md."
f" Flyway: {flyway_files}; Java/generated: {orm_files}")
if flyway_files or entity_files:
log_warning(
"Flyway scripts or JPA entities changed. Run './gradlew :db:test' and"
" './gradlew :core:sqlIntegrationTest' in addition to the standard tests.")
else:
log_success("No database schema or JPA entity changes found.")

def check_missing_tests():
print("\n--- Checking for Missing Tests ---")
diff_files = run_cmd("git diff HEAD^ --name-only").split('\n')
main_files_modified = False
test_files_modified = False

for f in diff_files:
if f.startswith('core/src/main/') or f.startswith('util/src/main/'):
if f.endswith('.java'):
main_files_modified = True
if f.startswith('core/src/test/') or f.startswith('util/src/test/'):
if f.endswith('Test.java'):
test_files_modified = True
diff_files = get_diff_files()
main_prefixes = tuple(f"{m}/src/main/" for m in TESTED_MODULES)
test_prefixes = tuple(f"{m}/src/test/" for m in TESTED_MODULES)
main_files_modified = any(
f.startswith(main_prefixes) and f.endswith('.java') for f in diff_files)
test_files_modified = any(
f.startswith(test_prefixes) and f.endswith('Test.java') for f in diff_files)

if main_files_modified and not test_files_modified:
log_warning("Production code (.java files in src/main/) was modified, but no corresponding tests (.java files in src/test/) were added or updated. You MUST proactively write tests for any new logic or bug fixes.")
Expand All @@ -337,10 +437,13 @@ def main():
check_commit_message()
check_license_headers()
check_missing_tests()
check_db_schema_split()
check_upstream_freshness()
check_formatting()
check_package_lock()
check_workspace_clean()
check_diff_anti_patterns()
check_internal_link_leaks()

print("\n========================================")
if errors_found == 0 and warnings_found == 0:
Expand Down
Loading
Loading