Skip to content

Commit 43c5eec

Browse files
darshitppdarshitpp
committed
Initial commit: java-code-upgrade skill
113 Java modernization patterns (Java 7-25) across 11 categories. Based on java.evolved by Bruno Borges (MIT License). Includes auto-sync CI for GitHub Actions and GitLab CI.
0 parents  commit 43c5eec

22 files changed

Lines changed: 6105 additions & 0 deletions

‎.github/workflows/sync-upstream.yml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
name: Sync from upstream java.evolved
2+
3+
on:
4+
schedule:
5+
# Weekly on Monday at 06:00 UTC
6+
- cron: '0 6 * * 1'
7+
workflow_dispatch: # Manual trigger from Actions tab
8+
9+
permissions:
10+
contents: write
11+
pull-requests: write
12+
13+
jobs:
14+
sync:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout this repo
18+
uses: actions/checkout@v4
19+
20+
- name: Clone upstream source
21+
run: |
22+
git clone --depth 1 https://github.com/javaevolved/javaevolved.github.io.git /tmp/upstream
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: '3.12'
28+
29+
- name: Gather upstream info
30+
id: upstream
31+
run: |
32+
YAML_COUNT=$(find /tmp/upstream/content -name "*.yaml" | wc -l | tr -d ' ')
33+
UPSTREAM_SHA=$(cd /tmp/upstream && git rev-parse --short HEAD)
34+
UPSTREAM_DATE=$(cd /tmp/upstream && git log -1 --format=%cs)
35+
echo "yaml_count=$YAML_COUNT" >> "$GITHUB_OUTPUT"
36+
echo "sha=$UPSTREAM_SHA" >> "$GITHUB_OUTPUT"
37+
echo "date=$UPSTREAM_DATE" >> "$GITHUB_OUTPUT"
38+
echo "Found $YAML_COUNT upstream patterns (commit $UPSTREAM_SHA from $UPSTREAM_DATE)"
39+
40+
- name: Regenerate references
41+
run: |
42+
python3 scripts/generate-references.py \
43+
--content-dir /tmp/upstream/content \
44+
--output-dir references/
45+
46+
- name: Check for changes
47+
id: changes
48+
run: |
49+
if git diff --quiet -- references/; then
50+
echo "has_changes=false" >> "$GITHUB_OUTPUT"
51+
echo "No changes detected — references are up to date."
52+
else
53+
echo "has_changes=true" >> "$GITHUB_OUTPUT"
54+
echo "Changes detected:"
55+
git diff --stat -- references/
56+
fi
57+
58+
- name: Create pull request
59+
if: steps.changes.outputs.has_changes == 'true'
60+
uses: peter-evans/create-pull-request@v6
61+
with:
62+
commit-message: "chore: sync references from upstream (${{ steps.upstream.outputs.sha }})"
63+
title: "Sync: Update patterns from java.evolved (${{ steps.upstream.outputs.date }})"
64+
body: |
65+
Automated sync from [javaevolved/javaevolved.github.io](https://github.com/javaevolved/javaevolved.github.io).
66+
67+
- Upstream commit: `${{ steps.upstream.outputs.sha }}`
68+
- Patterns found: ${{ steps.upstream.outputs.yaml_count }}
69+
70+
Review the reference file changes below to verify correctness.
71+
branch: sync/upstream-update
72+
delete-branch: true
73+
labels: automated,sync

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
__pycache__/
2+
*.pyc
3+
*.iml
4+
.idea/
5+
.DS_Store

‎.gitlab-ci.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
stages:
2+
- sync
3+
4+
sync-upstream:
5+
stage: sync
6+
image: python:3.12-slim
7+
rules:
8+
# Weekly schedule (configure in GitLab > CI/CD > Schedules: cron 0 6 * * 1)
9+
- if: $CI_PIPELINE_SOURCE == "schedule"
10+
# Manual trigger from UI
11+
- if: $CI_PIPELINE_SOURCE == "web"
12+
before_script:
13+
- apt-get update -qq && apt-get install -y -qq git > /dev/null
14+
- git config --global user.email "ci@${CI_SERVER_HOST}"
15+
- git config --global user.name "GitLab CI Sync Bot"
16+
script:
17+
# Clone upstream source
18+
- git clone --depth 1 https://github.com/javaevolved/javaevolved.github.io.git /tmp/upstream
19+
- YAML_COUNT=$(find /tmp/upstream/content -name "*.yaml" | wc -l | tr -d ' ')
20+
- UPSTREAM_SHA=$(cd /tmp/upstream && git rev-parse --short HEAD)
21+
- UPSTREAM_DATE=$(cd /tmp/upstream && git log -1 --format=%cs)
22+
- echo "Found $YAML_COUNT upstream patterns (commit $UPSTREAM_SHA from $UPSTREAM_DATE)"
23+
24+
# Regenerate references
25+
- python3 scripts/generate-references.py --content-dir /tmp/upstream/content --output-dir references/
26+
27+
# Check for changes
28+
- |
29+
if git diff --quiet -- references/; then
30+
echo "No changes detected — references are up to date."
31+
exit 0
32+
fi
33+
34+
# Push changes as a new MR branch
35+
- BRANCH="sync/upstream-${UPSTREAM_SHA}"
36+
- git checkout -b "$BRANCH"
37+
- git add references/
38+
- git commit -m "chore: sync references from upstream ($UPSTREAM_SHA)"
39+
- git remote set-url origin "https://oauth2:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
40+
- git push -o merge_request.create
41+
-o merge_request.title="Sync: Update patterns from java.evolved ($UPSTREAM_DATE)"
42+
-o merge_request.description="Automated sync from [javaevolved](https://github.com/javaevolved/javaevolved.github.io). Upstream commit: $UPSTREAM_SHA. Patterns: $YAML_COUNT."
43+
-o merge_request.remove_source_branch
44+
-o merge_request.label="automated,sync"
45+
origin "$BRANCH"

‎README.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# java-code-upgrade
2+
3+
An agent skill that helps developers upgrade Java code from older idioms to modern equivalents. Built on the comprehensive pattern database from [java.evolved](https://javaevolved.github.io/) by [Bruno Borges](https://github.com/brunoborges) ([source](https://github.com/javaevolved/javaevolved.github.io)).
4+
5+
## What it does
6+
7+
This skill enables AI coding agents to:
8+
9+
- **Detect legacy Java patterns** in codebases and suggest modern replacements
10+
- **Provide before/after code examples** for 113 patterns across 11 categories
11+
- **Guide enterprise migrations** from Java EE to Jakarta EE, Spring XML to annotations
12+
- **Filter by JDK version** to only suggest patterns compatible with the project's target
13+
- **Prioritize upgrades** by difficulty (beginner, intermediate, advanced)
14+
15+
## Coverage
16+
17+
| Category | Patterns | Examples |
18+
|-------------|----------|---------------------------------------------------------------------------------|
19+
| Language | 24 | var, records, sealed classes, pattern matching, switch expressions, text blocks |
20+
| Enterprise | 16 | EJB to CDI, Servlet to JAX-RS, JDBC to JPA, SOAP to REST, Spring modernization |
21+
| Streams | 12 | toList(), mapMulti(), gatherers, takeWhile/dropWhile, optional improvements |
22+
| Concurrency | 11 | Virtual threads, structured concurrency, scoped values, stable values |
23+
| Collections | 11 | List.of(), Map.of(), sequenced collections, unmodifiable collectors |
24+
| I/O | 11 | HTTP client, Files API, Path.of(), transferTo, memory-mapped files |
25+
| Strings | 7 | isBlank(), strip(), repeat(), lines(), formatted() |
26+
| Errors | 7 | Helpful NPE, multi-catch, optional chaining, null-in-switch |
27+
| Tooling | 8 | JShell, single-file execution, JFR, AOT preloading |
28+
| Date/Time | 6 | java.time API, Duration/Period, HexFormat, Math.clamp |
29+
| Security | 5 | PEM encoding, KDF, strong random, TLS defaults |
30+
| **Total** | **113** | **Java 7 through Java 25** |
31+
32+
## JDK Version Quick Reference
33+
34+
| JDK | Key Patterns |
35+
|-----|----------------------------------------------------------------------------|
36+
| 7 | multi-catch, diamond operator |
37+
| 8 | default/static interface methods, streams, CompletableFuture, java.time |
38+
| 9 | List/Set/Map.of(), Optional improvements, private interface methods |
39+
| 10 | var, unmodifiable copy |
40+
| 11 | String.isBlank/strip/repeat/lines, HTTP client, Path.of |
41+
| 14 | switch expressions, helpful NPE |
42+
| 15 | text blocks, String.formatted |
43+
| 16 | records, Stream.toList(), mapMulti |
44+
| 17 | sealed classes, RandomGenerator |
45+
| 21 | virtual threads, pattern matching, sequenced collections |
46+
| 22 | unnamed variables, FFM API |
47+
| 24 | stream gatherers |
48+
| 25 | structured concurrency, scoped values, stable values, compact source files |
49+
50+
## Installation
51+
52+
### Quick Install (recommended)
53+
54+
Install using [skills.sh](https://skills.sh/) — works with Claude Code, GitHub Copilot, Cursor, Cline, Windsurf, and 15+ other agents:
55+
56+
```bash
57+
npx skillsadd darshitpp/java-code-upgrade
58+
```
59+
60+
This auto-detects the agent and installs the skill in the correct location. No manual setup needed.
61+
62+
### Claude Code (manual)
63+
64+
There are two installation scopes:
65+
66+
**Global (available in all projects):**
67+
68+
```bash
69+
git clone https://github.com/darshitpp/java-code-upgrade.git ~/.claude/skills/java-code-upgrade
70+
```
71+
72+
**Per-project (available only in that project):**
73+
74+
```bash
75+
cd /path/to/your/project
76+
mkdir -p .claude/skills
77+
git clone https://github.com/darshitpp/java-code-upgrade.git .claude/skills/java-code-upgrade
78+
```
79+
80+
After installation, the skill appears automatically in Claude Code's available skills list. It triggers when asking to modernize Java code, review for outdated patterns, or upgrade JDK idioms. It can also be invoked explicitly with `/java-code-upgrade`.
81+
82+
To update the skill later:
83+
84+
```bash
85+
cd ~/.claude/skills/java-code-upgrade # or .claude/skills/java-code-upgrade
86+
git pull
87+
```
88+
89+
### Other Agent Frameworks
90+
91+
This skill follows the [agentskills.io](https://agentskills.io) specification:
92+
93+
- `SKILL.md` — core agent instructions (entry point)
94+
- `references/` — pattern database loaded on demand via progressive disclosure
95+
- `scripts/find-pattern.py` — CLI tool for programmatic pattern search
96+
- `assets/` — output templates
97+
98+
Clone the repo and point the agent framework at `SKILL.md` as the skill entry point.
99+
100+
## Directory Structure
101+
102+
```
103+
java-code-upgrade/
104+
SKILL.md # Core skill instructions
105+
scripts/
106+
find-pattern.py # CLI tool for searching patterns
107+
generate-references.py # Regenerates references from upstream YAML
108+
sync-from-source.sh # Pulls upstream and regenerates
109+
references/
110+
detection-patterns.md # Code signatures for detecting legacy patterns
111+
pattern-index.md # Quick lookup table of all 113 patterns
112+
language.md # Language feature patterns (23)
113+
collections.md # Collection patterns (11)
114+
strings.md # String patterns (7)
115+
streams.md # Stream patterns (12)
116+
concurrency.md # Concurrency patterns (11)
117+
io.md # I/O patterns (11)
118+
errors.md # Error handling patterns (7)
119+
datetime.md # Date/time patterns (6)
120+
security.md # Security patterns (5)
121+
tooling.md # Tooling patterns (8)
122+
enterprise.md # Enterprise migration patterns (16)
123+
assets/
124+
upgrade-report-template.md # Template for upgrade reports
125+
```
126+
127+
## Usage Examples
128+
129+
### Search patterns by category
130+
```bash
131+
python3 scripts/find-pattern.py --category concurrency --format brief
132+
```
133+
134+
### Find patterns for a specific JDK version
135+
```bash
136+
python3 scripts/find-pattern.py --min-jdk 17 --max-jdk 21 --format brief
137+
```
138+
139+
### Search by keyword
140+
```bash
141+
python3 scripts/find-pattern.py --keyword "virtual thread" --format full
142+
```
143+
144+
### Detect patterns in code
145+
```bash
146+
python3 scripts/find-pattern.py --detect 'Collections.unmodifiableList(Arrays.asList("a"))' --format brief
147+
```
148+
149+
## Keeping Up to Date
150+
151+
All files in `references/` are auto-generated from upstream YAML data. No manual editing needed.
152+
153+
The reference files can be automatically synced from the upstream [javaevolved](https://github.com/javaevolved/javaevolved.github.io) repository.
154+
155+
### Manual sync
156+
```bash
157+
./scripts/sync-from-source.sh
158+
```
159+
160+
### GitHub Actions (automated)
161+
162+
The included `.github/workflows/sync-upstream.yml` runs weekly and opens a pull request if patterns changed.
163+
164+
**Setup:**
165+
1. No extra tokens needed — the default `GITHUB_TOKEN` handles everything.
166+
2. The schedule runs weekly on Monday at 06:00 UTC. Adjust the cron in the workflow file if needed.
167+
3. Trigger manually anytime from **Actions > Sync from upstream java.evolved > Run workflow**.
168+
169+
### GitLab CI (automated)
170+
171+
The included `.gitlab-ci.yml` defines a `sync-upstream` job with the same behavior, opening a merge request on changes.
172+
173+
**Setup:**
174+
1. Go to **Settings > CI/CD > Variables** and add `GITLAB_TOKEN` — a project access token with `write_repository` and `api` scopes.
175+
2. Go to **CI/CD > Schedules** and create a new schedule with cron `0 6 * * 1` (weekly Monday 06:00 UTC) or any frequency you prefer.
176+
3. Trigger manually anytime from **CI/CD > Pipelines > Run pipeline**.
177+
178+
Both CI options create a PR/MR for review rather than pushing directly, so you can inspect changes before merging.
179+
180+
## Credits & Data Source
181+
182+
All pattern data is sourced from the **[java.evolved](https://javaevolved.github.io/)** project, created by [Bruno Borges](https://github.com/brunoborges). The original YAML content files have been consolidated into markdown reference files for efficient agent consumption with progressive disclosure.
183+
184+
- **Source repository:** [javaevolved/javaevolved.github.io](https://github.com/javaevolved/javaevolved.github.io)
185+
- **Original license:** [MIT License](https://github.com/javaevolved/javaevolved.github.io/blob/main/LICENSE) - Copyright (c) 2026 Bruno Borges
186+
187+
## License
188+
189+
MIT — same as the upstream source data.
190+
191+
```
192+
MIT License
193+
194+
Copyright (c) 2026 Bruno Borges
195+
196+
Permission is hereby granted, free of charge, to any person obtaining a copy
197+
of this software and associated documentation files (the "Software"), to deal
198+
in the Software without restriction, including without limitation the rights
199+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
200+
copies of the Software, and to permit persons to whom the Software is
201+
furnished to do so, subject to the following conditions:
202+
203+
The above copyright notice and this permission notice shall be included in all
204+
copies or substantial portions of the Software.
205+
206+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
207+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
208+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
209+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
210+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
211+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
212+
SOFTWARE.
213+
```

0 commit comments

Comments
 (0)