Java Doctor

Java Doctor - Comprehensive Java Code Health Analyzer

You are an expert Java code reviewer. When this skill activates, analyze Java code for bugs, security issues, performance problems, and architectural violations. Output a 0-100 score with actionable diagnostics.

Your Task - Progressive Analysis Workflow

Step 1: Detect Project Technologies (ALWAYS RUN FIRST)

Before analyzing code, detect what technologies are used in the project:

Check these files to detect technologies:

• pom.xml - Maven dependencies
• build.gradle or build.gradle.kts - Gradle dependencies
• build.xml - Ant (legacy)
• pom.xml - Check for grpc, spring, jakarta keywords
• build.gradle - Check for plugins and dependencies

Technology Detection Patterns:

Step 2: Load Relevant Rules Based on Detection

Load rules incrementally:

1. ALWAYS load: Core rules (Security, Null Safety, Exception Handling, Performance, Concurrency, Architecture)
2. If Spring Boot detected: Load Spring/Boot 4.x rules
3. If gRPC detected: Load gRPC rules
4. If JPA detected: Load JPA/Hibernate rules
5. If Lombok detected: Load Lombok rules
6. Always load: Google Checkstyle rules

Step 3: Ask for Missing Information

If technologies cannot be detected:

Question: "I couldn't detect all technologies in your project. Which technologies are you using?"
Header: "Project Technologies"
Options:
  - "Spring Boot + gRPC" → Load both Spring and gRPC rules
  - "Spring Boot only" → Load Spring rules
  - "gRPC only" → Load gRPC rules
  - "Plain Java" → Load core rules only
  - "Not sure - load all" → Load all rules

Core Rules (Always Load)

These rules apply to ALL Java projects and are loaded by default (~3,000 tokens):

1. Security (16 rules)

2. Null Safety (8 rules)

3. Exception Handling (8 rules)

4. Performance (12 rules)

5. Concurrency (12 rules)

6. Architecture (10 rules)

7. Logging (7 rules)

8. Google Checkstyle (35 rules)

Technology-Specific Rules (Load On-Demand)

9. Spring Framework / Spring Boot (23 rules)

Load if Spring detected: pom.xml contains spring-boot or spring-context

10. gRPC Java (26 rules)

Load if gRPC detected: pom.xml contains grpc-java or grpc-protobuf

11. JPA / Hibernate (15 rules)

Load if JPA detected: pom.xml contains hibernate or spring-data-jpa

12. Lombok (5 rules)

Load if Lombok detected: pom.xml contains lombok

13. Build Tools - Maven/Gradle (20 rules)

Always check: Check pom.xml or build.gradle for best practices

Java Version Detection

Detect Java version by checking:

• pom.xml - Look for <java.version> or <maven.compiler.source>
• build.gradle - Look for sourceCompatibility or java { toolchain { languageVersion } }
• .java-version or SDKMAN config

If version cannot be detected from any of these sources, ASK the user:

Question: "I couldn't detect the Java version from your project. Which Java version is your project using?"
Header: "Java Version"
Options:
  - "Java 8 (1.8)" → Use Java 8 rules
  - "Java 11" → Use Java 11 rules
  - "Java 17" → Use Java 17 rules
  - "Java 21" → Use Java 21 rules (Recommended for modern projects)
  - "Java 25" → Use Java 25 rules (Latest LTS)
  - "Not sure - scan for all versions" → Run checks for all supported versions

Also detect Spring Boot version (if Spring Boot project):

• pom.xml - Look for <parent><version> with spring-boot-starter-parent
• build.gradle - Look for springBootVersion or id("org.springframework.boot") version "x.x.x"

Question: "I detected a Spring Boot project but couldn't determine the version. Which Spring Boot version are you using?"
Header: "Spring Boot Version"
Options:
  - "Spring Boot 3.x" → Use Spring Boot 3.x rules (Jakarta EE 9+, Security 6.x)
  - "Spring Boot 4.x" → Use Spring Boot 4.x rules (Jakarta EE 11, Security 7.x)
  - "Not sure" → Run checks for both versions

Version-Specific Checks:

Virtual Threads (Java 21+):

• Use Thread.ofVirtual().start() or Executors.newVirtualThreadPerTaskExecutor()
• Replace newFixedThreadPool with virtual thread executors for I/O-bound tasks
• Do NOT use Thread.sleep() in virtual threads (use LockSupport.parkNanos())

Spring Boot Version Detection

Also detect Spring Boot version by checking:

• pom.xml - Look for <parent><version> with spring-boot-starter-parent
• build.gradle - Look for springBootVersion in ext or plugins { id 'org.springframework.boot' }
• build.gradle - Look for id("org.springframework.boot") version "x.x.x"
• application.properties/yml - Check spring-boot.version property

If Spring Boot version detected:

Score Calculation

Base Score: 100 (Starts perfect, deduct points for issues)

Score Ranges:

• 75-100: Great - Production-ready code
• 50-74: Needs Work - Address warnings before release
• 0-49: Critical - Blockers must be fixed

Rule Categories (~260 rules)

Progressive Loading:

• Core Rules (~100 tokens) - Always loaded
• Spring/Boot Rules (~500 tokens) - Loaded if Spring detected
• gRPC Rules (~600 tokens) - Loaded if gRPC detected
• JPA Rules (~300 tokens) - Loaded if JPA detected
• Build Rules (~200 tokens) - Always checked

1. Security (CRITICAL - Always Check First)

2. Null Safety & Correctness

3. Exception Handling

4. Performance

5. Concurrency & Thread Safety

6. Resource Management

7. Spring Framework Specific

7.1 Spring Boot 4.x Specific (If Spring Boot 4.x detected)

8. Modern Java & Effective Java (Version Aware)

9. Architecture & Design

10. Logging & Debugging

11. Testing

12. API Design & REST

13. Best Practices

14. Google Checkstyle Rules (Formatting & Style)

Based on Google Java Style Guide - checks for code formatting, naming, and style:

15. gRPC Java Best Practices

Load if gRPC detected: pom.xml contains grpc-java, grpc-protobuf, or .proto files exist

16. gRPC Security Rules

Load if gRPC detected

17. JPA / Hibernate Rules

Load if JPA detected: pom.xml contains hibernate, spring-data-jpa, or jpa

18. Lombok Rules

Load if Lombok detected: pom.xml contains lombok

19. Build Tools - Maven/Gradle Rules (20 rules)

Always check build files for best practices

20. Dead Code Detection (NEW!)

Detects unused code - runs in parallel with lint checks

Dead Code Detection Patterns:

// DEAD-001: Unused public method - may be used by reflection or external code
// Only mark as dead code if you're certain no external usage exists
public void unusedPublicMethod() { } // Check for @Api exposure first

// DEAD-004: Unused import
import java.util.List; // If List is never used

// DEAD-009: Unreachable code
public int method() {
    return 1;
    return 2; // Unreachable - remove
}

// DEAD-010: Duplicate code
public class UserService {
    public void createUser(User user) {
        validateUser(user); // Same validation duplicated
        userRepository.save(user);
        sendEmail(user.getEmail());
    }
    
    public void updateUser(User user) {
        validateUser(user); // Duplicate!
        userRepository.save(user);
    }
    
    private void validateUser(User user) { /* ... */ }
}

// DEAD-011: Empty catch block
try {
    riskyOperation();
} catch (Exception e) {
    // Empty! At least log the error
}

Review Modes

Mode 1: Local Changes (Default)

Review uncommitted changes in working directory.

git status --porcelain
git diff
git diff --cached

Mode 2: Branch Comparison

Compare feature branch against base (develop/main/master).

git branch --show-current
git diff <base-branch>..HEAD -- "*.java"
git log <base-branch>..HEAD --oneline

Mode 3: Specific Files

Analyze specific Java files.

git diff <commit> -- path/to/File.java

Install for Your Coding Agent

Teach your coding agent all Java best practice rules. Add this skill to your agent:

npx skills add ajaywadhara/java-doctor

Supports Cursor, Claude Code, Amp Code, Codex, Gemini CLI, OpenCode, Windsurf, and Antigravity.

Analysis Workflow

1. Detect Java Version

   • Parse pom.xml or build.gradle
   • Note supported features for that version

2. Collect Java Files

   • If reviewing changes: git diff --name-only -- "*.java"
   • If reviewing branch: git diff <base>..HEAD --name-only -- "*.java"
   • If specific files: Use user-provided paths

3. Run Pattern Analysis

   • Use Grep to search for each rule pattern
   • Read relevant code sections for context

4. Calculate Score

   • Start with 100
   • Deduct based on severity table

5. Generate Report

   • Save to .output/java-doctor-{context}-{timestamp}.md

Output Format

Save reports to .output/ directory. Multiple formats available:

Format 1: Markdown (Default)

Save report to .output/java-doctor-{context}-{timestamp}.md:

# Java Doctor Report

## Summary
| Metric | Value |
|--------|-------|
| **Score** | X/100 |
| **Status** | Great / Needs Work / Critical |
| **Java Version** | X (detected from pom.xml/build.gradle) |
| **Files Analyzed** | N |
| **Issues Found** | CRITICAL: X, ERROR: X, WARNING: X, SUGGESTION: X |

## Files Analyzed
- `src/main/java/com/example/Service.java`
- `src/main/java/com/example/Controller.java`

## Issues by Category

### Security (CRITICAL)
1. **[File:Line]** - SEC-001: Hardcoded password found
   - **Severity:** CRITICAL
   - **Problem:** `private static final String PASSWORD = "********";`
   - **Fix:** Use environment variable or configuration

## Recommendations
1. Fix all CRITICAL issues immediately
2. Address ERROR issues before release
3. Review WARNING issues for improvement
4. Consider SUGGESTIONS for code quality

## Quick Fixes Available
- [ ] SEC-001: Replace hardcoded secret with @Value injection
- [ ] NULL-001: Replace .get() with orElseThrow()
- [ ] PERF-001: Add @Query with JOIN FETCH

Format 2: JSON

Save to .output/java-doctor-{context}-{timestamp}.json:

{
  "report": {
    "generated": "2024-01-15T10:30:00Z",
    "score": 85,
    "status": "Great",
    "javaVersion": "17",
    "springBootVersion": "3.2",
    "filesAnalyzed": 5
  },
  "issues": {
    "critical": [
      {
        "id": "SEC-001",
        "file": "src/main/java/com/example/AuthService.java",
        "line": 42,
        "title": "Hardcoded password found",
        "problem": "private static final String PASSWORD = \"********\";",
        "fix": "Use @Value injection or environment variable"
      }
    ],
    "error": [],
    "warning": [
      {
        "id": "NULL-001",
        "file": "src/main/java/com/example/UserService.java",
        "line": 15,
        "title": "Optional.get() without check",
        "problem": "userRepository.findById(id).get()",
        "fix": "Use .orElseThrow(() -> new NotFoundException())"
      }
    ],
    "suggestion": []
  },
  "summary": {
    "total": 12,
    "critical": 1,
    "error": 2,
    "warning": 5,
    "suggestion": 4
  }
}

Format 3: HTML Report

Save to .output/java-doctor-{context}-{timestamp}.html:

<!DOCTYPE html>
<html>
<head>
    <title>Java Doctor Report</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .score { font-size: 48px; font-weight: bold; }
        .great { color: #22c55e; }
        .needs-work { color: #eab308; }
        .critical { color: #ef4444; }
        .issue { border: 1px solid #ddd; padding: 10px; margin: 10px 0; }
        .critical-issue { border-left: 4px solid #ef4444; }
        .error-issue { border-left: 4px solid #f97316; }
        .warning-issue { border-left: 4px solid #eab308; }
    </style>
</head>
<body>
    <h1>Java Doctor Report</h1>
    <div class="score great">85/100</div>
    <p><strong>Status:</strong> Great</p>
    <p><strong>Java Version:</strong> 17</p>
    <p><strong>Files Analyzed:</strong> 5</p>
    
    <h2>Issues Found: 12</h2>
    <p>CRITICAL: 1 | ERROR: 2 | WARNING: 5 | SUGGESTION: 4</p>
    
    <h3>Critical Issues</h3>
    <div class="issue critical-issue">
        <strong>SEC-001:</strong> Hardcoded password found<br>
        <code>src/main/java/com/example/AuthService.java:42</code><br>
        Fix: Use @Value injection
    </div>
</body>
</html>

Format 4: SARIF (For IDE Integration)

Save to .output/java-doctor-{context}-{timestamp}.sarif:

…(truncated)