devflow-kit 1.1.0 → 1.2.0

package/shared/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();
+```

package/shared/skills/java/references/patterns.md

@@ -0,0 +1,235 @@
+# Extended Java Patterns
+
+Correct patterns for Java development. Reference from main SKILL.md.
+
+---
+
+## Builder Pattern (Type-Safe)
+
+```java
+// Compile-time enforcement of required fields
+public record EmailMessage(String to, String subject, String body, List<String> cc) {
+
+    public static Builder builder() { return new Builder(); }
+
+    public static class Builder {
+        private String to;
+        private String subject;
+        private String body;
+        private List<String> cc = List.of();
+
+        public Builder to(String to) { this.to = Objects.requireNonNull(to); return this; }
+        public Builder subject(String subject) { this.subject = Objects.requireNonNull(subject); return this; }
+        public Builder body(String body) { this.body = Objects.requireNonNull(body); return this; }
+        public Builder cc(List<String> cc) { this.cc = List.copyOf(cc); return this; }
+
+        public EmailMessage build() {
+            Objects.requireNonNull(to, "to is required");
+            Objects.requireNonNull(subject, "subject is required");
+            Objects.requireNonNull(body, "body is required");
+            return new EmailMessage(to, subject, body, cc);
+        }
+    }
+}
+
+// Usage
+var email = EmailMessage.builder()
+    .to("user@example.com")
+    .subject("Welcome")
+    .body("Hello!")
+    .build();
+```
+
+---
+
+## Strategy via Interfaces
+
+```java
+// Define strategy as functional interface
+@FunctionalInterface
+public interface PricingStrategy {
+    Money calculatePrice(Order order);
+}
+
+// Implementations as lambdas or classes
+PricingStrategy standard = order -> order.subtotal();
+PricingStrategy discounted = order -> order.subtotal().multiply(0.9);
+PricingStrategy tiered = order -> {
+    if (order.itemCount() > 10) return order.subtotal().multiply(0.8);
+    if (order.itemCount() > 5) return order.subtotal().multiply(0.9);
+    return order.subtotal();
+};
+
+// Inject strategy
+public class OrderService {
+    private final PricingStrategy pricing;
+
+    public OrderService(PricingStrategy pricing) {
+        this.pricing = pricing;
+    }
+
+    public Money calculateTotal(Order order) {
+        return pricing.calculatePrice(order);
+    }
+}
+```
+
+---
+
+## Repository Pattern
+
+```java
+public interface UserRepository {
+    Optional<User> findById(String id);
+    List<User> findByEmail(String email);
+    User save(User user);
+    void deleteById(String id);
+    boolean existsById(String id);
+}
+
+// Implementation with constructor injection
+public class JpaUserRepository implements UserRepository {
+    private final EntityManager em;
+
+    public JpaUserRepository(EntityManager em) {
+        this.em = em;
+    }
+
+    @Override
+    public Optional<User> findById(String id) {
+        return Optional.ofNullable(em.find(User.class, id));
+    }
+
+    @Override
+    public User save(User user) {
+        return em.merge(user);
+    }
+}
+```
+
+---
+
+## Value Objects
+
+```java
+// Immutable value object with validation
+public record Money(BigDecimal amount, Currency currency) {
+    public Money {
+        Objects.requireNonNull(amount, "amount must not be null");
+        Objects.requireNonNull(currency, "currency must not be null");
+        if (amount.scale() > currency.getDefaultFractionDigits()) {
+            throw new IllegalArgumentException("Scale exceeds currency precision");
+        }
+    }
+
+    public Money add(Money other) {
+        requireSameCurrency(other);
+        return new Money(amount.add(other.amount), currency);
+    }
+
+    public Money multiply(double factor) {
+        return new Money(
+            amount.multiply(BigDecimal.valueOf(factor))
+                  .setScale(currency.getDefaultFractionDigits(), RoundingMode.HALF_UP),
+            currency
+        );
+    }
+
+    private void requireSameCurrency(Money other) {
+        if (!currency.equals(other.currency)) {
+            throw new IllegalArgumentException(
+                "Cannot combine %s and %s".formatted(currency, other.currency)
+            );
+        }
+    }
+}
+```
+
+---
+
+## Event-Driven Pattern
+
+```java
+// Domain event as sealed interface
+public sealed interface OrderEvent permits OrderCreated, OrderShipped, OrderCancelled {
+    String orderId();
+    Instant occurredAt();
+}
+
+public record OrderCreated(String orderId, Instant occurredAt, List<LineItem> items)
+    implements OrderEvent {}
+
+public record OrderShipped(String orderId, Instant occurredAt, String trackingNumber)
+    implements OrderEvent {}
+
+public record OrderCancelled(String orderId, Instant occurredAt, String reason)
+    implements OrderEvent {}
+
+// Event handler with exhaustive matching
+public class OrderEventHandler {
+    public void handle(OrderEvent event) {
+        switch (event) {
+            case OrderCreated e -> notifyWarehouse(e.items());
+            case OrderShipped e -> sendTrackingEmail(e.trackingNumber());
+            case OrderCancelled e -> processRefund(e.orderId(), e.reason());
+        }
+    }
+}
+```
+
+---
+
+## Stream Pipelines
+
+```java
+// Declarative collection processing
+public List<String> getActiveUserEmails(List<User> users) {
+    return users.stream()
+        .filter(User::isActive)
+        .map(User::email)
+        .filter(email -> email.contains("@"))
+        .sorted()
+        .toList(); // Unmodifiable list (Java 16+)
+}
+
+// Grouping and aggregation
+public Map<Department, Long> countByDepartment(List<Employee> employees) {
+    return employees.stream()
+        .collect(Collectors.groupingBy(Employee::department, Collectors.counting()));
+}
+
+// Reducing to summary
+public record OrderSummary(int count, Money total) {}
+
+public OrderSummary summarize(List<Order> orders) {
+    return orders.stream()
+        .reduce(
+            new OrderSummary(0, Money.ZERO),
+            (summary, order) -> new OrderSummary(
+                summary.count() + 1,
+                summary.total().add(order.total())
+            ),
+            (a, b) -> new OrderSummary(a.count() + b.count(), a.total().add(b.total()))
+        );
+}
+```
+
+---
+
+## Dependency Injection (Manual)
+
+```java
+// Composition root wires everything together
+public class Application {
+    public static void main(String[] args) {
+        var config = Config.load();
+        var dataSource = createDataSource(config);
+        var userRepo = new JpaUserRepository(dataSource);
+        var eventBus = new InMemoryEventBus();
+        var userService = new UserService(userRepo, eventBus);
+        var userController = new UserController(userService);
+
+        startServer(config.port(), userController);
+    }
+}
+```

package/shared/skills/java/references/violations.md

@@ -0,0 +1,213 @@
+# Common Java Violations
+
+Extended violation patterns for Java reviews. Reference from main SKILL.md.
+
+---
+
+## Null Returns
+
+### Returning null Instead of Optional
+
+```java
+// VIOLATION: Null return forces callers to null-check
+public User findById(String id) {
+    return userMap.get(id); // Returns null if absent
+}
+
+// Callers must remember to check:
+User user = findById(id);
+user.getName(); // NullPointerException if not found
+```
+
+### Nullable Collections
+
+```java
+// VIOLATION: Returning null instead of empty collection
+public List<Order> getOrders(String userId) {
+    List<Order> orders = orderMap.get(userId);
+    return orders; // null if user has no orders
+}
+
+// Callers iterate without checking:
+for (Order o : getOrders(userId)) { // NullPointerException
+    process(o);
+}
+```
+
+---
+
+## Raw Types
+
+### Unparameterized Generics
+
+```java
+// VIOLATION: Raw List - no type safety
+List users = new ArrayList();
+users.add("not a user"); // No compile error
+users.add(42);           // No compile error
+User first = (User) users.get(0); // ClassCastException at runtime
+
+// VIOLATION: Raw Map
+Map cache = new HashMap();
+cache.put(123, "value");
+String val = (String) cache.get(123); // Unsafe cast
+```
+
+### Raw Type in Method Signatures
+
+```java
+// VIOLATION: Raw Comparable
+public class Price implements Comparable {
+    public int compareTo(Object other) {
+        return Double.compare(this.amount, ((Price) other).amount); // Unsafe cast
+    }
+}
+
+// VIOLATION: Raw Iterator
+Iterator it = collection.iterator();
+while (it.hasNext()) {
+    String s = (String) it.next(); // Unsafe cast
+}
+```
+
+---
+
+## Checked Exception Abuse
+
+### Broad Throws Declarations
+
+```java
+// VIOLATION: throws Exception - hides what can actually go wrong
+public User createUser(String name) throws Exception {
+    // Callers must catch Exception, can't handle specific failures
+}
+
+// VIOLATION: Wrapping everything in checked exceptions
+public void process(String data) throws ProcessingException {
+    try {
+        Integer.parseInt(data);
+    } catch (NumberFormatException e) {
+        throw new ProcessingException("Failed", e); // Unnecessary wrapping
+    }
+}
+```
+
+### Swallowed Exceptions
+
+```java
+// VIOLATION: Empty catch block
+try {
+    connection.close();
+} catch (SQLException e) {
+    // silently ignored - resource leak hidden
+}
+
+// VIOLATION: Catching and logging only
+try {
+    processPayment(order);
+} catch (PaymentException e) {
+    logger.error("Payment failed", e);
+    // Continues as if nothing happened - order in inconsistent state
+}
+```
+
+---
+
+## Mutable Data Objects
+
+### JavaBean-Style Mutability
+
+```java
+// VIOLATION: Mutable DTO with setters
+public class UserDTO {
+    private String name;
+    private String email;
+
+    public void setName(String name) { this.name = name; }
+    public void setEmail(String email) { this.email = email; }
+    public String getName() { return name; }
+    public String getEmail() { return email; }
+}
+
+// Anyone can modify at any time:
+dto.setName("changed"); // No control over when/where mutation happens
+```
+
+### Exposing Internal Mutable State
+
+```java
+// VIOLATION: Getter returns mutable internal list
+public class Team {
+    private List<String> members = new ArrayList<>();
+
+    public List<String> getMembers() {
+        return members; // Caller can modify internal state
+    }
+}
+
+// External code breaks encapsulation:
+team.getMembers().clear(); // Empties the team's internal list
+```
+
+---
+
+## Deep Inheritance
+
+### Fragile Base Class
+
+```java
+// VIOLATION: Deep hierarchy creates tight coupling
+public abstract class AbstractEntity { ... }
+public abstract class AbstractAuditableEntity extends AbstractEntity { ... }
+public abstract class AbstractVersionedEntity extends AbstractAuditableEntity { ... }
+public class User extends AbstractVersionedEntity { ... }
+
+// Changing any base class ripples through all descendants
+// Testing requires understanding 4 levels of behavior
+```
+
+### Inheritance for Code Reuse
+
+```java
+// VIOLATION: Extending just to reuse utility methods
+public class OrderService extends BaseService {
+    // Only extends BaseService to get logAndAudit() method
+    public void processOrder(Order order) {
+        logAndAudit("processing", order.getId()); // Inherited utility
+    }
+}
+// Should be: inject a LogAuditService instead
+```
+
+---
+
+## Concurrency Violations
+
+### Shared Mutable State Without Synchronization
+
+```java
+// VIOLATION: HashMap accessed from multiple threads
+private Map<String, Session> sessions = new HashMap<>();
+
+public void addSession(String id, Session s) {
+    sessions.put(id, s); // Not thread-safe
+}
+```
+
+### Double-Checked Locking Done Wrong
+
+```java
+// VIOLATION: Missing volatile on lazily-initialized field
+private ExpensiveObject instance;
+
+public ExpensiveObject getInstance() {
+    if (instance == null) {
+        synchronized (this) {
+            if (instance == null) {
+                instance = new ExpensiveObject(); // Partially constructed object visible
+            }
+        }
+    }
+    return instance;
+}
+```