devflow-kit 1.0.0 → 1.2.0

package/plugins/devflow-java/skills/java/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: java
+description: This skill should be used when the user works with Java files (.java), asks about "records", "sealed classes", "Optional", "streams", "composition over inheritance", or discusses modern Java patterns and API design. Provides patterns for type system usage, error handling, immutability, and concurrency.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.java"
+  exclude:
+    - "**/build/**"
+    - "**/target/**"
+---
+
+# Java Patterns
+
+Reference for modern Java patterns, type system, and best practices.
+
+## Iron Law
+
+> **FAVOR COMPOSITION OVER INHERITANCE**
+>
+> Delegation and interfaces over class hierarchies. Inheritance creates tight coupling,
+> breaks encapsulation, and makes refactoring dangerous. Use interfaces for polymorphism,
+> records for data, and sealed classes for restricted hierarchies. Extend only when the
+> "is-a" relationship is genuinely invariant.
+
+## When This Skill Activates
+
+- Working with Java codebases
+- Designing APIs with modern Java features
+- Using records, sealed classes, Optional
+- Implementing concurrent code
+- Structuring Java packages
+
+---
+
+## Type System (Modern Java)
+
+### Records for Data
+
+```java
+// BAD: Mutable POJO with getters/setters
+// GOOD: Immutable record
+public record User(String name, String email, Instant createdAt) {
+    public User {
+        Objects.requireNonNull(name, "name must not be null");
+        Objects.requireNonNull(email, "email must not be null");
+    }
+}
+```
+
+### Sealed Classes for Restricted Hierarchies
+
+```java
+public sealed interface Result<T> permits Success, Failure {
+    record Success<T>(T value) implements Result<T> {}
+    record Failure<T>(String error) implements Result<T> {}
+}
+
+// Exhaustive pattern matching (Java 21+)
+switch (result) {
+    case Success<User> s -> handleSuccess(s.value());
+    case Failure<User> f -> handleError(f.error());
+}
+```
+
+### Optional for Absent Values
+
+```java
+// BAD: return null;
+// GOOD:
+public Optional<User> findById(String id) {
+    return Optional.ofNullable(userMap.get(id));
+}
+
+// BAD: if (optional.isPresent()) optional.get()
+// GOOD:
+optional.map(User::name).orElse("Anonymous");
+```
+
+---
+
+## Error Handling
+
+### Custom Exceptions with Context
+
+```java
+public class EntityNotFoundException extends RuntimeException {
+    private final String entityType;
+    private final String entityId;
+
+    public EntityNotFoundException(String entityType, String entityId) {
+        super("%s with id %s not found".formatted(entityType, entityId));
+        this.entityType = entityType;
+        this.entityId = entityId;
+    }
+}
+```
+
+### Try-with-Resources
+
+```java
+// Always use try-with-resources for AutoCloseable
+try (var conn = dataSource.getConnection();
+     var stmt = conn.prepareStatement(sql)) {
+    stmt.setString(1, id);
+    return mapResult(stmt.executeQuery());
+}
+```
+
+---
+
+## Immutability
+
+```java
+// Prefer unmodifiable collections
+List<String> names = List.of("Alice", "Bob");
+Map<String, Integer> scores = Map.of("Alice", 100, "Bob", 95);
+
+// Defensive copies in constructors
+public final class Team {
+    private final List<String> members;
+    public Team(List<String> members) {
+        this.members = List.copyOf(members);
+    }
+    public List<String> members() { return members; }
+}
+```
+
+---
+
+## Composition Over Inheritance
+
+```java
+// BAD: class UserService extends BaseService extends AbstractDAO
+// GOOD: compose via constructor injection
+public class UserService {
+    private final UserRepository repository;
+    private final EventPublisher events;
+
+    public UserService(UserRepository repository, EventPublisher events) {
+        this.repository = repository;
+        this.events = events;
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Returning null | `return null` | `return Optional.empty()` |
+| Checked exception abuse | `throws Exception` | Specific exceptions or unchecked |
+| Raw types | `List list` | `List<User> list` |
+| Deep inheritance | 4+ level hierarchy | Interfaces + composition |
+| Mutable data objects | `setName()/getName()` | Records or immutable classes |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Common Java violations
+- `references/patterns.md` - Extended Java patterns
+- `references/detection.md` - Detection patterns for Java issues
+- `references/modern-java.md` - Modern Java features (17-21+)
+
+---
+
+## Checklist
+
+- [ ] Records for pure data types
+- [ ] Sealed interfaces for type hierarchies
+- [ ] Optional instead of null returns
+- [ ] Composition over inheritance
+- [ ] Try-with-resources for all AutoCloseable
+- [ ] Immutable collections (List.of, Map.of)
+- [ ] No raw generic types
+- [ ] Custom exceptions with context
+- [ ] Streams for collection transforms
+- [ ] Constructor injection for dependencies

package/plugins/devflow-java/skills/java/references/detection.md

@@ -0,0 +1,120 @@
+# Detection Patterns for Java Issues
+
+Grep and regex patterns for automated detection of Java violations. Reference from main SKILL.md.
+
+---
+
+## Null Returns
+
+```bash
+# Methods returning null instead of Optional
+rg 'return\s+null\s*;' --type java
+
+# Nullable method parameters without validation
+rg 'public\s+\w+\s+\w+\((?!.*@NonNull).*\)' --type java
+```
+
+---
+
+## Raw Types
+
+```bash
+# Raw List, Map, Set, Collection usage
+rg '\b(List|Map|Set|Collection|Iterator|Iterable)\b(?!\s*<)' --type java
+
+# Raw Comparable implementation
+rg 'implements\s+Comparable\b(?!\s*<)' --type java
+
+# Unsafe casts from Object
+rg '\(\s*(String|Integer|Long|Double)\s*\)\s*\w+\.get' --type java
+```
+
+---
+
+## Deep Inheritance
+
+```bash
+# Classes extending non-Object/non-interface classes (potential deep hierarchy)
+rg 'class\s+\w+\s+extends\s+(?!Object\b)\w+' --type java
+
+# Abstract class chains (look for multiple levels)
+rg 'abstract\s+class\s+\w+\s+extends\s+Abstract' --type java
+
+# Count inheritance depth per file
+rg 'extends\s+\w+' --type java --count
+```
+
+---
+
+## Missing Try-with-Resources
+
+```bash
+# Manual close() calls (should use try-with-resources)
+rg '\.close\(\)\s*;' --type java
+
+# InputStream/OutputStream/Connection created outside try-with-resources
+rg 'new\s+(FileInputStream|FileOutputStream|BufferedReader|BufferedWriter|Socket)\(' --type java
+
+# getConnection() without try-with-resources context
+rg '\.getConnection\(\)' --type java
+```
+
+---
+
+## Checked Exception Abuse
+
+```bash
+# Broad throws declarations
+rg 'throws\s+Exception\b' --type java
+
+# Empty catch blocks
+rg -U 'catch\s*\([^)]+\)\s*\{\s*\}' --type java --multiline
+
+# Catch-and-ignore (catch with only a comment or log)
+rg -U 'catch\s*\([^)]+\)\s*\{\s*(//|/\*|logger\.(debug|trace))' --type java --multiline
+```
+
+---
+
+## Mutable Data Objects
+
+```bash
+# Setter methods (JavaBean anti-pattern for data objects)
+rg 'public\s+void\s+set[A-Z]\w*\(' --type java
+
+# Mutable collections returned from getters
+rg 'return\s+(this\.)?(list|map|set|collection)\s*;' --type java -i
+
+# Missing defensive copies in constructors
+rg 'this\.\w+\s*=\s*\w+\s*;' --type java
+```
+
+---
+
+## Concurrency Issues
+
+```bash
+# HashMap in concurrent context (should be ConcurrentHashMap)
+rg 'new\s+HashMap\b' --type java
+
+# Missing volatile on shared fields
+rg 'private\s+(?!volatile\s)(?!final\s)\w+\s+\w+\s*=' --type java
+
+# Synchronized on non-private lock object
+rg 'synchronized\s*\(\s*this\s*\)' --type java
+```
+
+---
+
+## Streams Anti-Patterns
+
+```bash
+# Stream.forEach with side effects (should use for-loop or collect)
+rg '\.stream\(\).*\.forEach\(' --type java
+
+# Nested streams (performance concern)
+rg '\.stream\(\).*\.stream\(\)' --type java
+
+# collect(Collectors.toList()) instead of .toList() (Java 16+)
+rg 'collect\(Collectors\.toList\(\)\)' --type java
+```

package/plugins/devflow-java/skills/java/references/modern-java.md

@@ -0,0 +1,270 @@
+# Modern Java Features (17-21+)
+
+Deep-dive on modern Java language features. Reference from main SKILL.md.
+
+---
+
+## Records (Java 16+)
+
+### Basic Record
+
+```java
+// Immutable data carrier with auto-generated equals, hashCode, toString
+public record Point(double x, double y) {}
+
+// Usage
+var p = new Point(3.0, 4.0);
+double x = p.x(); // Accessor method, not getX()
+```
+
+### Compact Constructor (Validation)
+
+```java
+public record Email(String value) {
+    public Email {
+        Objects.requireNonNull(value, "email must not be null");
+        if (!value.contains("@")) {
+            throw new IllegalArgumentException("Invalid email: " + value);
+        }
+        value = value.toLowerCase().strip(); // Reassign before final assignment
+    }
+}
+```
+
+### Record with Custom Methods
+
+```java
+public record Range(int start, int end) {
+    public Range {
+        if (start > end) throw new IllegalArgumentException("start must be <= end");
+    }
+
+    public int length() { return end - start; }
+    public boolean contains(int value) { return value >= start && value <= end; }
+    public Range overlap(Range other) {
+        int newStart = Math.max(start, other.start);
+        int newEnd = Math.min(end, other.end);
+        return newStart <= newEnd ? new Range(newStart, newEnd) : null;
+    }
+}
+```
+
+### Records as Local Classes
+
+```java
+public List<String> processOrders(List<Order> orders) {
+    // Local record for intermediate computation
+    record OrderTotal(String orderId, Money total) {}
+
+    return orders.stream()
+        .map(o -> new OrderTotal(o.id(), o.calculateTotal()))
+        .filter(ot -> ot.total().isGreaterThan(Money.of(100)))
+        .map(OrderTotal::orderId)
+        .toList();
+}
+```
+
+---
+
+## Sealed Classes (Java 17+)
+
+### Sealed Interface
+
+```java
+public sealed interface Shape permits Circle, Rectangle, Triangle {
+    double area();
+}
+
+public record Circle(double radius) implements Shape {
+    public double area() { return Math.PI * radius * radius; }
+}
+
+public record Rectangle(double width, double height) implements Shape {
+    public double area() { return width * height; }
+}
+
+public record Triangle(double base, double height) implements Shape {
+    public double area() { return 0.5 * base * height; }
+}
+```
+
+### Sealed Class with Abstract Methods
+
+```java
+public sealed abstract class Payment permits CreditCard, BankTransfer, Crypto {
+    abstract Money amount();
+    abstract String reference();
+}
+
+public final class CreditCard extends Payment {
+    private final String cardLast4;
+    private final Money amount;
+    // ...
+}
+
+public final class BankTransfer extends Payment { /* ... */ }
+public final class Crypto extends Payment { /* ... */ }
+```
+
+---
+
+## Pattern Matching (Java 21+)
+
+### Switch with Patterns
+
+```java
+// Exhaustive pattern matching on sealed types
+public String describe(Shape shape) {
+    return switch (shape) {
+        case Circle c    -> "Circle with radius %.2f".formatted(c.radius());
+        case Rectangle r -> "Rectangle %s x %s".formatted(r.width(), r.height());
+        case Triangle t  -> "Triangle with base %.2f".formatted(t.base());
+    };
+}
+```
+
+### Guarded Patterns
+
+```java
+public String classifyTemperature(Object obj) {
+    return switch (obj) {
+        case Integer i when i < 0    -> "Freezing";
+        case Integer i when i < 15   -> "Cold";
+        case Integer i when i < 25   -> "Comfortable";
+        case Integer i               -> "Hot";
+        case Double d when d < 0.0   -> "Freezing";
+        case Double d                -> "Warm-ish (%.1f)".formatted(d);
+        case String s                -> "Not a temperature: " + s;
+        case null                    -> "No reading";
+        default                      -> "Unknown type";
+    };
+}
+```
+
+### Record Patterns (Destructuring)
+
+```java
+// Nested destructuring
+record Address(String city, String country) {}
+record Person(String name, Address address) {}
+
+public String greet(Object obj) {
+    return switch (obj) {
+        case Person(var name, Address(var city, _)) ->
+            "Hello %s from %s".formatted(name, city);
+        default -> "Hello stranger";
+    };
+}
+```
+
+---
+
+## Text Blocks (Java 15+)
+
+```java
+// Multi-line strings with proper indentation
+String json = """
+        {
+            "name": "%s",
+            "email": "%s",
+            "active": true
+        }
+        """.formatted(user.name(), user.email());
+
+String sql = """
+        SELECT u.id, u.name, u.email
+        FROM users u
+        JOIN orders o ON o.user_id = u.id
+        WHERE u.active = true
+          AND o.created_at > ?
+        ORDER BY u.name
+        """;
+```
+
+---
+
+## Virtual Threads (Java 21+)
+
+### Basic Virtual Thread
+
+```java
+// Lightweight thread - does not pin platform thread during I/O
+Thread.startVirtualThread(() -> {
+    var result = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+    process(result.body());
+});
+```
+
+### Structured Concurrency (Preview)
+
+```java
+// All subtasks complete or cancel together
+try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+    Subtask<User> userTask = scope.fork(() -> fetchUser(userId));
+    Subtask<List<Order>> ordersTask = scope.fork(() -> fetchOrders(userId));
+
+    scope.join().throwIfFailed();
+
+    return new UserDashboard(userTask.get(), ordersTask.get());
+}
+```
+
+### ExecutorService with Virtual Threads
+
+```java
+// Process thousands of concurrent I/O tasks
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Response>> futures = urls.stream()
+        .map(url -> executor.submit(() -> httpClient.send(
+            HttpRequest.newBuilder(URI.create(url)).build(),
+            HttpResponse.BodyHandlers.ofString()
+        )))
+        .toList();
+
+    List<Response> responses = futures.stream()
+        .map(f -> {
+            try { return f.get(); }
+            catch (Exception e) { throw new RuntimeException(e); }
+        })
+        .toList();
+}
+```
+
+---
+
+## Other Modern Features
+
+### Enhanced instanceof (Java 16+)
+
+```java
+// Pattern variable binding eliminates explicit cast
+if (obj instanceof String s && s.length() > 5) {
+    System.out.println(s.toUpperCase());
+}
+
+// Works with negation
+if (!(obj instanceof String s)) {
+    throw new IllegalArgumentException("Expected String");
+}
+// s is in scope here
+process(s);
+```
+
+### Helpful NullPointerExceptions (Java 14+)
+
+```java
+// JVM now tells you exactly which reference was null:
+// java.lang.NullPointerException: Cannot invoke "String.length()"
+//   because the return value of "User.name()" is null
+// Enable with: -XX:+ShowCodeDetailsInExceptionMessages (default since Java 17)
+```
+
+### Stream Gatherers (Java 22+ Preview)
+
+```java
+// Custom intermediate stream operations
+var windowedAverages = temperatures.stream()
+    .gather(Gatherers.windowSliding(5))
+    .map(window -> window.stream().mapToDouble(d -> d).average().orElse(0))
+    .toList();
+```