@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/java/java-collections-streams/references/stream-pipelines.md

@@ -0,0 +1,165 @@
+# Stream Pipelines
+
+## Lazy Evaluation
+
+Streams are lazy - intermediate operations don't execute until a terminal operation is called.
+
+```java
+// Nothing happens until collect() is called
+Stream<String> lazy = items.stream()
+    .peek(i -> System.out.println("Processing: " + i))  // Not called yet
+    .filter(i -> i.length() > 3)
+    .map(String::toUpperCase);
+
+// Terminal operation triggers execution
+List<String> result = lazy.collect(Collectors.toList());
+```
+
+## Short-Circuit Operations
+
+```java
+// findFirst - stops at first match
+Optional<User> first = users.stream()
+    .filter(User::isAdmin)
+    .findFirst();
+
+// anyMatch - stops when condition is true
+boolean hasAdmin = users.stream()
+    .anyMatch(User::isAdmin);
+
+// limit - stops after n elements
+List<User> topThree = users.stream()
+    .sorted(Comparator.comparing(User::getScore).reversed())
+    .limit(3)
+    .toList();
+
+// takeWhile (Java 9+) - takes elements while predicate is true
+List<Integer> untilNegative = numbers.stream()
+    .takeWhile(n -> n >= 0)
+    .toList();
+
+// dropWhile (Java 9+) - drops elements while predicate is true
+List<Integer> afterNegative = numbers.stream()
+    .dropWhile(n -> n < 0)
+    .toList();
+```
+
+## Advanced Mapping
+
+```java
+// flatMap for one-to-many
+List<Tag> allTags = posts.stream()
+    .flatMap(post -> post.getTags().stream())
+    .distinct()
+    .toList();
+
+// mapMulti (Java 16+) - more efficient flatMap alternative
+List<Integer> doubled = numbers.stream()
+    .<Integer>mapMulti((num, consumer) -> {
+        consumer.accept(num);
+        consumer.accept(num * 2);
+    })
+    .toList();
+
+// Conditional mapping
+List<String> processed = items.stream()
+    .map(item -> switch (item.getType()) {
+        case A -> processTypeA(item);
+        case B -> processTypeB(item);
+        default -> item.getName();
+    })
+    .toList();
+```
+
+## Reducing Operations
+
+```java
+// Simple reduce
+int sum = numbers.stream()
+    .reduce(0, Integer::sum);
+
+// Reduce with identity, accumulator, combiner (for parallel)
+int total = orders.parallelStream()
+    .reduce(
+        0,                              // identity
+        (acc, order) -> acc + order.getTotal(),  // accumulator
+        Integer::sum                    // combiner (for parallel)
+    );
+
+// Collect vs Reduce
+// Use collect for mutable reduction (building collections)
+List<String> list = stream.collect(Collectors.toList());
+
+// Use reduce for immutable reduction (computing single value)
+Optional<BigDecimal> total = amounts.stream()
+    .reduce(BigDecimal::add);
+```
+
+## Parallel Streams
+
+```java
+// When to use parallel streams:
+// 1. Large dataset (> 10,000 elements)
+// 2. CPU-bound operations (not I/O)
+// 3. Independent operations (no shared mutable state)
+// 4. Splittable data source (ArrayList, arrays)
+
+// Good use case
+long count = hugeList.parallelStream()  // ArrayList, large
+    .filter(this::cpuIntensiveCheck)     // CPU-bound
+    .count();
+
+// Bad use cases
+// - LinkedList (not easily splittable)
+// - I/O operations (blocking, not CPU-bound)
+// - Small datasets (overhead > benefit)
+// - Operations with side effects
+
+// Custom thread pool for parallel streams
+ForkJoinPool customPool = new ForkJoinPool(4);
+List<Result> results = customPool.submit(() ->
+    items.parallelStream()
+        .map(this::process)
+        .toList()
+).get();
+```
+
+## Infinite Streams
+
+```java
+// Generate infinite stream
+Stream<UUID> uuids = Stream.generate(UUID::randomUUID);
+
+// Iterate with seed
+Stream<Integer> evens = Stream.iterate(0, n -> n + 2);
+
+// Iterate with predicate (Java 9+)
+Stream<Integer> limited = Stream.iterate(1, n -> n < 100, n -> n * 2);
+
+// Use with limit
+List<UUID> fiveUuids = Stream.generate(UUID::randomUUID)
+    .limit(5)
+    .toList();
+```
+
+## Debugging Streams
+
+```java
+// peek for debugging (remove in production)
+List<String> result = items.stream()
+    .peek(i -> log.debug("Before filter: {}", i))
+    .filter(Item::isActive)
+    .peek(i -> log.debug("After filter: {}", i))
+    .map(Item::getName)
+    .peek(n -> log.debug("After map: {}", n))
+    .toList();
+
+// Breakpoint-friendly version
+List<String> result = items.stream()
+    .filter(item -> {
+        boolean active = item.isActive();  // Set breakpoint here
+        return active;
+    })
+    .map(Item::getName)
+    .toList();
+```

package/rules/java/java-concurrency/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: Java Concurrency
+description: Thread management, Executor framework, CompletableFuture, synchronization, and virtual threads.
+metadata:
+  labels: [java, concurrency, threads, async]
+  triggers:
+    files: ['**/*.java']
+    keywords: [Thread, Runnable, Executor, CompletableFuture, synchronized, Lock, Atomic, Future, Callable, ExecutorService]
+---
+
+# Java Concurrency Standards
+
+## Executor Framework
+
+```java
+// Fixed thread pool - bounded, predictable
+ExecutorService executor = Executors.newFixedThreadPool(
+    Runtime.getRuntime().availableProcessors()
+);
+
+// Cached thread pool - unbounded, use carefully
+ExecutorService cached = Executors.newCachedThreadPool();
+
+// Scheduled executor
+ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(2);
+scheduler.scheduleAtFixedRate(task, 0, 1, TimeUnit.SECONDS);
+
+// Virtual threads (Java 21+)
+ExecutorService virtual = Executors.newVirtualThreadPerTaskExecutor();
+
+// Custom thread pool
+ThreadPoolExecutor custom = new ThreadPoolExecutor(
+    4,                      // core pool size
+    8,                      // max pool size
+    60, TimeUnit.SECONDS,   // keep alive
+    new LinkedBlockingQueue<>(100),  // work queue
+    new ThreadPoolExecutor.CallerRunsPolicy()  // rejection handler
+);
+
+// Always shutdown executors
+try {
+    executor.shutdown();
+    if (!executor.awaitTermination(30, TimeUnit.SECONDS)) {
+        executor.shutdownNow();
+    }
+} catch (InterruptedException e) {
+    executor.shutdownNow();
+    Thread.currentThread().interrupt();
+}
+```
+
+## CompletableFuture
+
+```java
+// Async execution
+CompletableFuture<User> userFuture = CompletableFuture
+    .supplyAsync(() -> userService.findById(id), executor);
+
+// Chaining
+CompletableFuture<String> result = userFuture
+    .thenApply(User::getEmail)
+    .thenApply(String::toLowerCase)
+    .exceptionally(ex -> "unknown@example.com");
+
+// Combine multiple futures
+CompletableFuture<UserProfile> profile = CompletableFuture
+    .allOf(userFuture, ordersFuture, preferencesFuture)
+    .thenApply(v -> new UserProfile(
+        userFuture.join(),
+        ordersFuture.join(),
+        preferencesFuture.join()
+    ));
+
+// Either/race
+CompletableFuture<String> fastest = CompletableFuture
+    .anyOf(primaryService, fallbackService)
+    .thenApply(result -> (String) result);
+
+// Timeout (Java 9+)
+CompletableFuture<User> withTimeout = userFuture
+    .orTimeout(5, TimeUnit.SECONDS)
+    .exceptionally(ex -> defaultUser);
+```
+
+## Synchronization
+
+```java
+// synchronized block - prefer over method
+private final Object lock = new Object();
+
+public void update(String value) {
+    synchronized (lock) {
+        // critical section
+    }
+}
+
+// ReentrantLock - more flexible
+private final ReentrantLock lock = new ReentrantLock();
+
+public void process() {
+    lock.lock();
+    try {
+        // critical section
+    } finally {
+        lock.unlock();
+    }
+}
+
+// ReadWriteLock - multiple readers, single writer
+private final ReadWriteLock rwLock = new ReentrantReadWriteLock();
+
+public String read() {
+    rwLock.readLock().lock();
+    try {
+        return data;
+    } finally {
+        rwLock.readLock().unlock();
+    }
+}
+
+public void write(String value) {
+    rwLock.writeLock().lock();
+    try {
+        data = value;
+    } finally {
+        rwLock.writeLock().unlock();
+    }
+}
+```
+
+## Atomic Classes
+
+```java
+// Atomic primitives
+AtomicInteger counter = new AtomicInteger(0);
+counter.incrementAndGet();
+counter.compareAndSet(expected, newValue);
+
+// Atomic reference
+AtomicReference<Config> configRef = new AtomicReference<>(initialConfig);
+configRef.updateAndGet(config -> config.withNewValue(value));
+
+// LongAdder for high contention
+LongAdder adder = new LongAdder();
+adder.increment();
+long sum = adder.sum();
+```
+
+## Virtual Threads (Java 21+)
+
+```java
+// Simple virtual thread
+Thread.startVirtualThread(() -> {
+    // blocking I/O is fine
+    String data = httpClient.get(url);
+    process(data);
+});
+
+// With executor
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Result>> futures = tasks.stream()
+        .map(task -> executor.submit(task::execute))
+        .toList();
+
+    for (Future<Result> future : futures) {
+        results.add(future.get());
+    }
+}
+
+// Don't use with CPU-bound tasks
+// Don't use synchronized for long operations (use ReentrantLock)
+```
+
+## Best Practices
+
+1. **Prefer high-level constructs** (Executor, CompletableFuture) over raw threads
+2. **Size thread pools** based on task type (CPU-bound: cores, I/O-bound: higher)
+3. **Always handle InterruptedException** - restore interrupt status
+4. **Use virtual threads** for I/O-bound tasks (Java 21+)
+5. **Prefer Atomic classes** over synchronized for simple counters
+6. **Immutability** is the best synchronization
+
+## References
+
+- [Executor Patterns](references/executor-patterns.md) - Thread pool configuration, shutdown
+- [CompletableFuture](references/completable-future.md) - Async composition patterns
+- [Virtual Threads](references/virtual-threads.md) - Java 21+ patterns

package/rules/java/java-concurrency/references/REFERENCE.md

@@ -0,0 +1,17 @@
+# Java Concurrency References
+
+## References
+
+- [**Executor Patterns**](executor-patterns.md) - Thread pool sizing, configuration, graceful shutdown
+- [**CompletableFuture**](completable-future.md) - Async composition, error handling, timeouts
+- [**Virtual Threads**](virtual-threads.md) - Java 21+ patterns, when to use, pitfalls
+
+## Quick Checks
+
+- [ ] Use ExecutorService over raw Thread creation
+- [ ] Size thread pools appropriately (CPU-bound: cores, I/O-bound: higher)
+- [ ] Always shutdown executors in finally/try-with-resources
+- [ ] Handle InterruptedException - restore interrupt status
+- [ ] Use virtual threads for I/O-bound tasks (Java 21+)
+- [ ] Prefer immutability over synchronization
+- [ ] Use AtomicXxx for simple counters, Lock for complex critical sections

package/rules/java/java-concurrency/references/completable-future.md

@@ -0,0 +1,165 @@
+# CompletableFuture Patterns
+
+## Basic Composition
+
+```java
+// Async execution with custom executor
+CompletableFuture<User> userFuture = CompletableFuture
+    .supplyAsync(() -> userRepository.findById(id), ioExecutor);
+
+// Transform result
+CompletableFuture<String> emailFuture = userFuture
+    .thenApply(User::getEmail);
+
+// Async transformation
+CompletableFuture<Profile> profileFuture = userFuture
+    .thenApplyAsync(user -> profileService.load(user), ioExecutor);
+
+// Consume result
+userFuture.thenAccept(user -> log.info("Loaded user: {}", user.getName()));
+
+// Run after completion (no access to result)
+userFuture.thenRun(() -> metrics.increment("user.loaded"));
+```
+
+## Combining Futures
+
+```java
+// Combine two futures
+CompletableFuture<UserWithOrders> combined = userFuture
+    .thenCombine(ordersFuture, (user, orders) -> new UserWithOrders(user, orders));
+
+// Chain dependent futures
+CompletableFuture<List<OrderDetails>> details = userFuture
+    .thenCompose(user -> orderService.findByUser(user.getId()));
+
+// Wait for all
+CompletableFuture<Void> all = CompletableFuture.allOf(
+    future1, future2, future3
+);
+
+// Get results after allOf
+CompletableFuture<List<Result>> results = all.thenApply(v -> List.of(
+    future1.join(),
+    future2.join(),
+    future3.join()
+));
+
+// First to complete (race)
+CompletableFuture<String> fastest = CompletableFuture.anyOf(
+    primaryService.call(),
+    backupService.call()
+).thenApply(result -> (String) result);
+```
+
+## Error Handling
+
+```java
+// Recover from exception
+CompletableFuture<User> withFallback = userFuture
+    .exceptionally(ex -> {
+        log.warn("Failed to load user: {}", ex.getMessage());
+        return User.guest();
+    });
+
+// Handle both success and failure
+CompletableFuture<Result> handled = userFuture
+    .handle((user, ex) -> {
+        if (ex != null) {
+            return Result.failure(ex);
+        }
+        return Result.success(user);
+    });
+
+// Async exception handling
+CompletableFuture<User> recovered = userFuture
+    .exceptionallyAsync(ex -> loadFromCache(id), cacheExecutor);
+
+// whenComplete - observe without changing result
+userFuture.whenComplete((user, ex) -> {
+    if (ex != null) {
+        metrics.increment("user.load.failed");
+    } else {
+        metrics.increment("user.load.success");
+    }
+});
+```
+
+## Timeouts (Java 9+)
+
+```java
+// Timeout with exception
+CompletableFuture<User> withTimeout = userFuture
+    .orTimeout(5, TimeUnit.SECONDS);
+
+// Timeout with fallback value
+CompletableFuture<User> withFallback = userFuture
+    .completeOnTimeout(User.guest(), 5, TimeUnit.SECONDS);
+
+// Manual timeout (pre-Java 9)
+CompletableFuture<User> manual = new CompletableFuture<>();
+scheduler.schedule(
+    () -> manual.completeExceptionally(new TimeoutException()),
+    5, TimeUnit.SECONDS
+);
+userFuture.thenAccept(manual::complete);
+```
+
+## Parallel Execution
+
+```java
+// Execute multiple independent tasks in parallel
+public CompletableFuture<Dashboard> loadDashboard(String userId) {
+    CompletableFuture<User> userF = loadUser(userId);
+    CompletableFuture<List<Order>> ordersF = loadOrders(userId);
+    CompletableFuture<Preferences> prefsF = loadPreferences(userId);
+    CompletableFuture<Recommendations> recsF = loadRecommendations(userId);
+
+    return CompletableFuture.allOf(userF, ordersF, prefsF, recsF)
+        .thenApply(v -> new Dashboard(
+            userF.join(),
+            ordersF.join(),
+            prefsF.join(),
+            recsF.join()
+        ));
+}
+
+// Collect results from list of futures
+public <T> CompletableFuture<List<T>> allOf(List<CompletableFuture<T>> futures) {
+    return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
+        .thenApply(v -> futures.stream()
+            .map(CompletableFuture::join)
+            .toList());
+}
+```
+
+## Best Practices
+
+```java
+// 1. Always specify executor for async operations
+CompletableFuture.supplyAsync(task, executor);  // Good
+CompletableFuture.supplyAsync(task);  // Uses ForkJoinPool.commonPool() - careful
+
+// 2. Use join() in composition, get() when you need checked exceptions
+results.stream()
+    .map(CompletableFuture::join)  // In stream context
+    .toList();
+
+try {
+    result.get(5, TimeUnit.SECONDS);  // When timeout/exception handling needed
+} catch (TimeoutException | ExecutionException e) {
+    // handle
+}
+
+// 3. Don't block in async chains
+userFuture
+    .thenApply(user -> {
+        // DON'T: orderService.findByUser(user.getId()).get(); // Blocks!
+        // DO: return orderService.findByUser(user.getId());
+        return user.getName();
+    });
+
+// 4. Use thenCompose for dependent async operations
+userFuture.thenCompose(user -> loadOrders(user.getId()));  // Good
+// Not: userFuture.thenApply(user -> loadOrders(user.getId()).join());  // Blocks
+```

package/rules/java/java-concurrency/references/executor-patterns.md

@@ -0,0 +1,176 @@
+# Executor Patterns
+
+## Thread Pool Sizing
+
+```java
+// CPU-bound tasks: cores or cores + 1
+int cpuBound = Runtime.getRuntime().availableProcessors();
+
+// I/O-bound tasks: cores * (1 + wait/compute ratio)
+// If tasks spend 80% waiting: cores * 5
+int ioBound = cpuBound * 5;
+
+// Mixed workloads: separate pools
+ExecutorService cpuPool = Executors.newFixedThreadPool(cpuBound);
+ExecutorService ioPool = Executors.newFixedThreadPool(ioBound);
+```
+
+## Custom Thread Pool
+
+```java
+// Production-ready configuration
+ThreadPoolExecutor executor = new ThreadPoolExecutor(
+    4,                              // corePoolSize
+    16,                             // maximumPoolSize
+    60L, TimeUnit.SECONDS,          // keepAliveTime
+    new LinkedBlockingQueue<>(1000), // workQueue with bounded capacity
+    new ThreadFactoryBuilder()
+        .setNameFormat("worker-%d")
+        .setUncaughtExceptionHandler((t, e) -> log.error("Thread {} failed", t, e))
+        .build(),
+    new ThreadPoolExecutor.CallerRunsPolicy()  // backpressure
+);
+
+// Allow core threads to timeout (saves resources when idle)
+executor.allowCoreThreadTimeOut(true);
+
+// Pre-start core threads (faster initial response)
+executor.prestartAllCoreThreads();
+```
+
+## Rejection Policies
+
+```java
+// AbortPolicy (default) - throws RejectedExecutionException
+new ThreadPoolExecutor.AbortPolicy()
+
+// CallerRunsPolicy - caller thread executes the task (backpressure)
+new ThreadPoolExecutor.CallerRunsPolicy()
+
+// DiscardPolicy - silently discards
+new ThreadPoolExecutor.DiscardPolicy()
+
+// DiscardOldestPolicy - discards oldest waiting task
+new ThreadPoolExecutor.DiscardOldestPolicy()
+
+// Custom policy
+RejectedExecutionHandler custom = (r, executor) -> {
+    log.warn("Task rejected, queue full: {}", executor.getQueue().size());
+    // Maybe save to database for later processing
+    taskRepository.save(r);
+};
+```
+
+## Graceful Shutdown
+
+```java
+public void shutdown(ExecutorService executor) {
+    executor.shutdown();  // No new tasks accepted
+
+    try {
+        // Wait for existing tasks to complete
+        if (!executor.awaitTermination(30, TimeUnit.SECONDS)) {
+            log.warn("Executor did not terminate in time, forcing shutdown");
+            List<Runnable> pending = executor.shutdownNow();
+            log.warn("{} tasks were cancelled", pending.size());
+
+            // Wait again for tasks to respond to interrupt
+            if (!executor.awaitTermination(10, TimeUnit.SECONDS)) {
+                log.error("Executor did not terminate");
+            }
+        }
+    } catch (InterruptedException e) {
+        executor.shutdownNow();
+        Thread.currentThread().interrupt();
+    }
+}
+
+// With lifecycle hook (Spring)
+@PreDestroy
+public void cleanup() {
+    shutdown(executor);
+}
+```
+
+## Scheduled Executor
+
+```java
+ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(2);
+
+// One-time delay
+scheduler.schedule(() -> sendReminder(), 1, TimeUnit.HOURS);
+
+// Fixed rate (starts every N seconds, regardless of duration)
+scheduler.scheduleAtFixedRate(
+    () -> collectMetrics(),
+    0,                    // initial delay
+    30, TimeUnit.SECONDS  // period
+);
+
+// Fixed delay (N seconds after previous completion)
+scheduler.scheduleWithFixedDelay(
+    () -> processQueue(),
+    0,                    // initial delay
+    5, TimeUnit.SECONDS   // delay between end and next start
+);
+
+// Handle exceptions in scheduled tasks
+scheduler.scheduleAtFixedRate(() -> {
+    try {
+        riskyOperation();
+    } catch (Exception e) {
+        log.error("Scheduled task failed", e);
+        // Don't rethrow - task would stop repeating
+    }
+}, 0, 1, TimeUnit.MINUTES);
+```
+
+## Fork/Join Pool
+
+```java
+// For recursive divide-and-conquer tasks
+ForkJoinPool forkJoinPool = new ForkJoinPool(
+    Runtime.getRuntime().availableProcessors()
+);
+
+class SumTask extends RecursiveTask<Long> {
+    private final long[] array;
+    private final int start, end;
+    private static final int THRESHOLD = 10_000;
+
+    @Override
+    protected Long compute() {
+        if (end - start <= THRESHOLD) {
+            return computeDirectly();
+        }
+
+        int mid = (start + end) / 2;
+        SumTask left = new SumTask(array, start, mid);
+        SumTask right = new SumTask(array, mid, end);
+
+        left.fork();  // async
+        long rightResult = right.compute();  // sync
+        long leftResult = left.join();  // wait
+
+        return leftResult + rightResult;
+    }
+}
+
+Long result = forkJoinPool.invoke(new SumTask(array, 0, array.length));
+```
+
+## Monitoring
+
+```java
+// Get metrics from ThreadPoolExecutor
+ThreadPoolExecutor executor = (ThreadPoolExecutor) Executors.newFixedThreadPool(4);
+
+int activeCount = executor.getActiveCount();
+long completedTasks = executor.getCompletedTaskCount();
+int queueSize = executor.getQueue().size();
+int poolSize = executor.getPoolSize();
+
+// Expose via metrics library
+meterRegistry.gauge("executor.active", executor, ThreadPoolExecutor::getActiveCount);
+meterRegistry.gauge("executor.queue.size", executor, e -> e.getQueue().size());
+```