Skip to content

asharma157/tech-stack-upgrade

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
frontend
frontend
 
 
java_migration.egg-info
java_migration.egg-info
 
 
java_migration
java_migration
 
 
.DS_Store
.DS_Store
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

Java Migration Agent

Autonomous AI-powered migration skill factory for Java Maven projects. A single graph-based pipeline (Google ADK Workflow) executes pluggable migration recipe skills:

  • spring-boot-2-to-3 (default) — Spring Boot 2 / Java 8-11 → Spring Boot 3.3.5 / Java 21
  • quarkus-migration — Spring Boot → Quarkus (local-commit delivery)

Give it a GitHub URL or local repo path, and it will analyse, migrate, validate, and deliver the result as a GitHub Pull Request (or local commit / zip, per the recipe) — ready for manual review.

Adding a new migration target (Gradle, Micronaut, Java 25, ...) means dropping a new skill folder into java_migration/skills/ — no new pipeline, no new agents.

Quick Start (Web UI)

pip install -e .                                   # backend + CLI
cd frontend && npm install && npm run build && cd ..
jmigrate serve                                     # → http://127.0.0.1:8000

Full setup, dev-mode, and troubleshooting instructions: frontend/README.md

What It Migrates

POM Dependencies

Component From To
Spring Boot Parent 2.x 3.3.5
Java Version 8 / 11 21
Hibernate 5.x (org.hibernate) 6.4.4.Final (org.hibernate.orm)
Apache CXF 3.x 4.0.4
SnakeYAML 1.x 2.2 (fixes CVE-2022-1471)
JUnit 4.x (junit:junit) 5.10.2 (org.junit.jupiter:junit-jupiter)
Mockito 4.x 5.11.0
Surefire Plugin 2.x 3.2.5
javax.* dependencies javax.servlet, javax.validation, javax.persistence, javax.ws.rs jakarta equivalents with pinned versions

Java Source Code

Pattern Before After
Servlet imports javax.servlet.* jakarta.servlet.*
Validation imports javax.validation.* jakarta.validation.*
Persistence imports javax.persistence.* jakarta.persistence.*
JAX-RS imports javax.ws.rs.* jakarta.ws.rs.*
Annotation imports javax.annotation.* jakarta.annotation.*
CDI imports javax.inject.*, javax.enterprise.* jakarta.inject.*, jakarta.enterprise.*
JAXB imports javax.xml.bind.* jakarta.xml.bind.*
Mail imports javax.mail.* jakarta.mail.*

11 javax package namespaces are migrated in total. Packages that remain in the java.* namespace (javax.crypto, javax.net, javax.swing, etc.) are not touched.

Test Files (JUnit 4 to JUnit 5)

Pattern Before After
Test annotation org.junit.Test org.junit.jupiter.api.Test
Setup/teardown @Before / @After @BeforeEach / @AfterEach
Class-level setup @BeforeClass / @AfterClass @BeforeAll / @AfterAll
Skip test @Ignore @Disabled
Runner model @RunWith(MockitoJUnitRunner.class) @ExtendWith(MockitoExtension.class)
Assertions org.junit.Assert.* org.junit.jupiter.api.Assertions.*
Spring 6 deprecation .getStatusCodeValue() .getStatusCode().value()

Security Scanning

Dependency CVE checks against a built-in database:

  • SnakeYAML (CVE-2022-1471), Log4Shell (CVE-2021-44228), Jackson (CVE-2020-36518)
  • Hibernate (CVE-2020-25638), Spring Web (CVE-2024-22243), CXF (CVE-2022-46364)
  • Deprecated javax.servlet and JUnit 4 (CVE-2020-15250)

Code pattern analysis (regex-based static analysis):

  • SQL injection, XXE vulnerabilities, hardcoded secrets
  • Insecure randomness, path traversal, unsafe deserialization
  • Weak cryptography (DES, RC4, MD5, SHA-1), CORS wildcard misconfig

Architecture: one pipeline, pluggable recipe skills

The migration runs as a single 5-stage graph Workflow (ADK 2.0). Migration knowledge lives in skill packages (SKILL.md + references), not in the agents:

                 GitHub URL or local path (+ optional recipe)
                                  │
                                  ▼
                ┌─────────────────────────────────┐
                │  1. PLANNER (read-only)          │      java_migration/skills/
                │  Validates repo, parses POM,     │◄──── recipe catalog rendered
                │  SELECTS THE RECIPE SKILL,       │      into instruction
                │  identifies migration tasks      │
                └────────────────┬────────────────┘
                                 │  planner_output (repo_root + selected_skill)
                                 ▼
                ┌─────────────────────────────────┐
                │  2. MIGRATOR (generic executor)  │◄──── load_skill(selected)
                │  Loads the recipe via            │      via SkillToolset, then
                │  SkillToolset, calls its tool    │      follows its tool-call
                │  sequence                        │      sequence
                └────────────────┬────────────────┘
                                 ▼
                ┌─────────────────────────────────┐
                │  3. SECURITY SCANNER             │◄──── security-baseline skill
                │  CVE dependency check,           │      (owns cve-database.json)
                │  code pattern analysis           │
                └────────────────┬────────────────┘
                                 ▼
                ┌─────────────────────────────────┐
                │  4. VALIDATOR                    │◄──── validation-maven skill
                │  mvn compile, mvn test,          │
                │  auto-fix cycle (up to 10x)      │
                └────────────────┬────────────────┘
                                 ▼
                ┌─────────────────────────────────┐
                │  5. PACKAGER                     │◄──── packaging-git skill +
                │  Change report, then PR /        │      per-recipe delivery
                │  local commit / zip per the      │      params (branch, commit
                │  recipe's delivery params        │      message, PR title)
                └─────────────────────────────────┘

Two kinds of skills (metadata.category in the SKILL.md frontmatter):

  • migration-recipe — one per migration target. Declares its transform-tool sequence and delivery parameters. The planner picks one at runtime; the migrator loads it and follows it.
  • pipeline-stage — shared stages (security, validation, packaging). Their SKILL.md body is the agent's playbook, loaded at build time — the SKILL.md file is the single source of truth.

Guardrails at every stage:

  • validate_repo() prevents placeholder or invalid paths from propagating (build marker configurable per recipe)
  • check_pipeline_state() lets agents halt the pipeline on critical errors
  • Each agent verifies the previous stage succeeded before proceeding

Adding a new migration target

  1. Create java_migration/skills/<recipe-name>/SKILL.md with:
    • frontmatter: name, description, metadata.category: migration-recipe, metadata.tools, metadata.delivery (branch_name, commit_message, pr_title, local_commit_only)
    • body: the exact tool-call sequence, summary format, and closing line
  2. Add any new deterministic transform tools under java_migration/tools/ and register them in the migrator's tool superset (agents/migrator.py)
  3. Optionally add references/ files (version tables, mappings) next to the SKILL.md

That's it — the planner's catalog, the packager's delivery table, and jmigrate recipes all pick the new skill up automatically.

Prerequisites

Requirement Purpose Required?
Python 3.11+ Runtime Yes
Git Clone repos, create branches, push Yes
GitHub CLI (gh) Create pull requests Yes (for PR delivery)
Maven (mvn) Compile and test validation Optional (validation is skipped if missing)
Java 21 Required by Maven for compilation Optional (only if Maven is used)

GitHub CLI Setup

# Install
brew install gh          # macOS
# or: apt install gh     # Debian/Ubuntu
# or: winget install GitHub.cli  # Windows

# Authenticate
gh auth login
gh auth status           # verify

Installation

cd java_migration
pip install -e .

This installs the jmigrate CLI command.

Usage

CLI

# Migrate from a GitHub URL (clones, migrates, raises PR) — default recipe
jmigrate run https://github.com/owner/repo

# Migrate a local repo (migrates in place, creates ZIP)
jmigrate run /path/to/your/java-project

# Pick a migration recipe explicitly
jmigrate run /path/to/your/java-project --to quarkus-migration

# List available migration recipes
jmigrate recipes

# Check migration status
jmigrate status /path/to/your/java-project

Web UI (recommended)

# One-time: build the frontend
cd java_migration/frontend && npm install && npm run build && cd ..

# Serve UI + API at http://127.0.0.1:8000
jmigrate serve

The UI presents two tiles:

  • Java migration — Spring Boot 2 → 3 / Java 21
  • Quarkus migration — opt-in second step for an already-migrated app

Each tile accepts a GitHub URL (delivered as a pull request, linked in the UI) or a local folder (picked via the browser, copied into a temp workspace — same lifecycle as a clone — and delivered as a zip; the UI shows the temp paths). A stage tracker follows the pipeline live: plan → migrate → security scan → validate → deliver.

For frontend development: jmigrate serve in one terminal, cd frontend && npm run dev in another (vite proxies /api to :8000).

ADK Web UI

cd java_migration
adk web .

Then in the web UI, send:

Migrate https://github.com/owner/repo

How Delivery Works

GitHub URL Input (PR delivery)

  1. The repo is cloned from the default branch (main or master)
  2. A feature branch migration/spring-boot-3-java-21 is created
  3. The migration pipeline runs on the feature branch
  4. Changes are committed, the branch is pushed, and a PR is created
  5. The PR is not merged — it's ready for manual review

The PR body contains the full migration change report.

Local Path Input (ZIP delivery)

  1. The migration pipeline runs in place
  2. A ZIP archive of all changed files is created in the repo directory
  3. The ZIP includes the change report and change log

Output

Change Report

Every migration generates .migration/REPORT.md with categorized changes:

  • POM changes — dependency version updates, groupId swaps
  • javax-to-jakarta — import namespace migrations per file
  • junit-migration — test framework upgrades per file
  • security-cve — dependency vulnerability findings
  • security-code — code pattern analysis findings

Change Log

Detailed JSON log at .migration/changes.json used by the packager to track every individual modification.

Project Structure

java_migration/
├── pyproject.toml                    # Package config, CLI entrypoint
├── frontend/                         # Vite web UI (tiles, stage tracker)
│   ├── index.html
│   └── src/main.js, src/style.css
├── java_migration/
│   ├── main.py                       # CLI (jmigrate run/serve/recipes/status)
│   ├── server.py                     # FastAPI: REST API + static frontend
│   ├── service.py                    # Job manager: runs the Workflow headless
│   ├── agent.py                      # Root Workflow (single graph pipeline)
│   ├── skills_loader.py              # Loads skill packages, renders catalogs
│   ├── skills/                       # ★ THE SKILL FACTORY
│   │   ├── spring-boot-2-to-3/       #   recipe: SB2→SB3/Java 21
│   │   │   ├── SKILL.md
│   │   │   └── references/           #   pom/javax/junit mapping tables
│   │   ├── quarkus-migration/        #   recipe: Spring Boot → Quarkus
│   │   │   ├── SKILL.md
│   │   │   └── references/
│   │   ├── security-baseline/        #   stage: CVE + code scan playbook
│   │   │   ├── SKILL.md
│   │   │   └── references/cve-database.json   # single source of truth
│   │   ├── validation-maven/SKILL.md #   stage: compile/test/fix (10 cycles)
│   │   └── packaging-git/SKILL.md    #   stage: report + PR/commit/zip
│   ├── agents/
│   │   ├── planner.py                # Stage 1: Analysis + recipe selection
│   │   ├── migrator.py               # Stage 2: Generic recipe executor
│   │   ├── security_scanner.py       # Stage 3: CVE + code scan
│   │   ├── validator.py              # Stage 4: Build + test (10 fix cycles)
│   │   └── packager.py               # Stage 5: Report + deliver
│   └── tools/
│       ├── github_tools.py           # Clone, branch, commit, push, PR
│       ├── migration_tools.py        # POM, javax→jakarta, JUnit 4→5
│       ├── quarkus_migration_tools.py # Quarkus POM/annotation transforms
│       ├── analysis_tools.py         # POM parsing, file scanning
│       ├── security_tools.py         # CVE + code pattern scanner
│       ├── validation_tools.py       # Maven compile/test + auto-fix
│       ├── packaging_tools.py        # ZIP + delivery mode detection
│       └── guardrails.py             # Repo validation, pipeline state

Tech Stack

  • Google ADK 2.x — Agent orchestration (graph Workflow + SkillToolset skill packages)
  • LiteLLM — LLM abstraction (supports Ollama, Gemini, etc.)
  • lxml — XML/POM parsing for dependency analysis
  • Typer + Rich — CLI interface
  • NetworkX — Dependency graph analysis

Limitations

  • Only supports Maven projects (pom.xml). Gradle is not supported.
  • Migration transforms are deterministic regex/string replacements — complex refactoring (e.g., custom Spring Security config rewrite) requires manual work.
  • Security scanning uses a built-in CVE database (8 entries), not a live feed. For comprehensive scanning, integrate Snyk or SonarQube.
  • Validation requires Maven and Java 21 installed locally. If unavailable, validation is skipped (the PR is still created).
  • The LLM is used for orchestration and error diagnosis, not for code generation — all code transforms are in deterministic Python tools.

License

Private — internal use only.

About

Upgrade Java version, migrate to quarkus

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages