@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/java/build-maven/references/dependency-management.md

@@ -0,0 +1,111 @@
+# Maven Dependency Management
+
+## Dependency Scopes
+
+```xml
+<dependencies>
+    <!-- compile (default) - available everywhere -->
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+
+    <!-- provided - compile only, container provides at runtime -->
+    <dependency>
+        <groupId>jakarta.servlet</groupId>
+        <artifactId>jakarta.servlet-api</artifactId>
+        <scope>provided</scope>
+    </dependency>
+
+    <!-- runtime - not needed for compile -->
+    <dependency>
+        <groupId>org.postgresql</groupId>
+        <artifactId>postgresql</artifactId>
+        <scope>runtime</scope>
+    </dependency>
+
+    <!-- test - only for tests -->
+    <dependency>
+        <groupId>org.junit.jupiter</groupId>
+        <artifactId>junit-jupiter</artifactId>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+```
+
+## BOM (Bill of Materials)
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <!-- Import BOM -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-dependencies</artifactId>
+            <version>3.2.0</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+
+        <!-- Now use without version -->
+    </dependencies>
+</dependencyManagement>
+
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-web</artifactId>
+        <!-- Version inherited from BOM -->
+    </dependency>
+</dependencies>
+```
+
+## Exclusions
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-web</artifactId>
+    <exclusions>
+        <exclusion>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-tomcat</artifactId>
+        </exclusion>
+    </exclusions>
+</dependency>
+
+<!-- Replace with Jetty -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-jetty</artifactId>
+</dependency>
+```
+
+## Version Properties
+
+```xml
+<properties>
+    <java.version>21</java.version>
+    <spring-boot.version>3.2.0</spring-boot.version>
+    <lombok.version>1.18.30</lombok.version>
+</properties>
+
+<dependencies>
+    <dependency>
+        <groupId>org.projectlombok</groupId>
+        <artifactId>lombok</artifactId>
+        <version>${lombok.version}</version>
+        <scope>provided</scope>
+    </dependency>
+</dependencies>
+```
+
+## Optional Dependencies
+
+```xml
+<dependency>
+    <groupId>com.example</groupId>
+    <artifactId>optional-feature</artifactId>
+    <optional>true</optional>
+</dependency>
+```

package/rules/java/build-maven/references/lifecycle-phases.md

@@ -0,0 +1,114 @@
+# Maven Lifecycle Phases
+
+## Default Lifecycle
+
+```xml
+<!-- Phase order: validate → compile → test → package → verify → install → deploy -->
+
+<!-- Skip tests during build -->
+<properties>
+    <maven.test.skip>true</maven.test.skip>
+    <!-- Or just skip execution, still compile -->
+    <skipTests>true</skipTests>
+</properties>
+```
+
+## Common Commands
+
+```bash
+# Clean and build
+mvn clean install
+
+# Build without tests
+mvn clean install -DskipTests
+
+# Run specific phase
+mvn compile
+mvn test
+mvn package
+
+# Run with profile
+mvn clean install -Pproduction
+
+# Debug output
+mvn clean install -X
+
+# Dependency tree
+mvn dependency:tree
+
+# Effective POM
+mvn help:effective-pom
+```
+
+## Plugin Configuration
+
+```xml
+<build>
+    <plugins>
+        <!-- Compiler plugin -->
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.11.0</version>
+            <configuration>
+                <source>21</source>
+                <target>21</target>
+                <compilerArgs>
+                    <arg>--enable-preview</arg>
+                </compilerArgs>
+            </configuration>
+        </plugin>
+
+        <!-- Surefire for unit tests -->
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <version>3.1.2</version>
+            <configuration>
+                <includes>
+                    <include>**/*Test.java</include>
+                </includes>
+            </configuration>
+        </plugin>
+
+        <!-- Failsafe for integration tests -->
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-failsafe-plugin</artifactId>
+            <version>3.1.2</version>
+            <executions>
+                <execution>
+                    <goals>
+                        <goal>integration-test</goal>
+                        <goal>verify</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+```
+
+## Multi-Module Project
+
+```xml
+<!-- Parent POM -->
+<project>
+    <groupId>com.example</groupId>
+    <artifactId>parent</artifactId>
+    <version>1.0.0</version>
+    <packaging>pom</packaging>
+
+    <modules>
+        <module>core</module>
+        <module>api</module>
+        <module>web</module>
+    </modules>
+
+    <dependencyManagement>
+        <dependencies>
+            <!-- Centralize versions here -->
+        </dependencies>
+    </dependencyManagement>
+</project>
+```

package/rules/java/graalvm-native/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: GraalVM Native
+description: Native image compilation, reflection configuration, and build optimization.
+metadata:
+  labels: [java, graalvm, native, aot]
+  triggers:
+    files: ['**/*.java', 'native-image.properties', 'META-INF/native-image/**', 'pom.xml', 'build.gradle']
+    keywords: [GraalVM, native-image, reflection-config, reachability-metadata, '@RegisterForReflection']
+---
+
+# GraalVM Native Standards
+
+## Building Native Image
+
+```bash
+# Maven with Spring Boot
+./mvnw -Pnative native:compile
+
+# Maven with Quarkus
+./mvnw package -Dnative
+
+# Gradle
+./gradlew nativeCompile
+```
+
+## Reflection Configuration
+
+```java
+// Quarkus - register for reflection
+@RegisterForReflection
+public class User {
+    private String name;
+    private String email;
+}
+
+// Spring Boot - hints
+@Configuration
+@ImportRuntimeHints(MyRuntimeHints.class)
+public class NativeConfig {}
+
+public class MyRuntimeHints implements RuntimeHintsRegistrar {
+    @Override
+    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
+        hints.reflection().registerType(User.class,
+            MemberCategory.PUBLIC_FIELDS,
+            MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS,
+            MemberCategory.INVOKE_PUBLIC_METHODS);
+    }
+}
+```
+
+## Native Image Configuration Files
+
+```
+src/main/resources/META-INF/native-image/
+├── reflect-config.json
+├── resource-config.json
+├── serialization-config.json
+└── native-image.properties
+```
+
+```json
+// reflect-config.json
+[
+  {
+    "name": "com.example.User",
+    "allDeclaredConstructors": true,
+    "allPublicMethods": true,
+    "allDeclaredFields": true
+  }
+]
+```
+
+```json
+// resource-config.json
+{
+  "resources": {
+    "includes": [
+      {"pattern": "application\\.yml"},
+      {"pattern": "db/migration/.*"}
+    ]
+  }
+}
+```
+
+## Performance Tips
+
+```java
+// Use build-time initialization
+@BuildTimeInit
+public class Constants {
+    public static final Map<String, String> CONFIG = loadConfig();
+}
+
+// Avoid runtime class loading
+// DON'T: Class.forName("com.example.MyClass")
+// DO: Reference classes directly
+
+// Use static configuration
+// Avoid dynamic proxies when possible
+```
+
+## References
+
+- [Native Image Config](references/native-image-config.md) - Full configuration options

package/rules/java/graalvm-native/references/REFERENCE.md

@@ -0,0 +1,12 @@
+# GraalVM Native References
+
+## References
+
+- [**Native Image Config**](native-image-config.md) - Reflection, resources, serialization config
+
+## Quick Checks
+
+- [ ] Register classes for reflection explicitly
+- [ ] Include resource files in resource-config.json
+- [ ] Avoid dynamic class loading
+- [ ] Test native image in CI before release

package/rules/java/java-collections-streams/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: Java Collections & Streams
+description: Collections framework, Stream API, functional interfaces, and Optional patterns.
+metadata:
+  labels: [java, collections, streams, functional]
+  triggers:
+    files: ['**/*.java']
+    keywords: [List, Map, Set, Stream, Optional, Collector, Collectors, HashMap, ArrayList, LinkedList, TreeMap]
+---
+
+# Java Collections & Streams Standards
+
+## Collections Framework
+
+```java
+// Choose the right collection
+List<String> list = new ArrayList<>();     // Random access, dynamic size
+List<String> linked = new LinkedList<>();  // Frequent insertions/deletions
+Set<String> set = new HashSet<>();         // Unique elements, O(1) lookup
+Set<String> sorted = new TreeSet<>();      // Sorted unique elements
+Map<K, V> map = new HashMap<>();           // Key-value pairs, O(1) lookup
+Map<K, V> linked = new LinkedHashMap<>();  // Insertion order preserved
+Map<K, V> tree = new TreeMap<>();          // Sorted by keys
+
+// Immutable collections (Java 9+)
+List<String> immutable = List.of("a", "b", "c");
+Set<Integer> immutableSet = Set.of(1, 2, 3);
+Map<String, Integer> immutableMap = Map.of("a", 1, "b", 2);
+
+// Unmodifiable wrappers
+List<String> unmodifiable = Collections.unmodifiableList(mutableList);
+// Or with copyOf (Java 10+)
+List<String> copy = List.copyOf(mutableList);
+```
+
+## Stream API
+
+```java
+// Basic pipeline
+List<String> result = items.stream()
+    .filter(item -> item.isActive())
+    .map(Item::getName)
+    .sorted()
+    .distinct()
+    .collect(Collectors.toList());
+
+// Parallel streams (use with caution)
+long count = largeList.parallelStream()
+    .filter(this::expensiveCheck)
+    .count();
+
+// FlatMap for nested structures
+List<String> allTags = posts.stream()
+    .flatMap(post -> post.getTags().stream())
+    .distinct()
+    .toList();  // Java 16+
+
+// Reduce operations
+int sum = numbers.stream()
+    .reduce(0, Integer::sum);
+
+Optional<Integer> max = numbers.stream()
+    .reduce(Integer::max);
+```
+
+## Collectors
+
+```java
+// Group by
+Map<Status, List<Order>> byStatus = orders.stream()
+    .collect(Collectors.groupingBy(Order::getStatus));
+
+// Group by with downstream collector
+Map<Status, Long> countByStatus = orders.stream()
+    .collect(Collectors.groupingBy(
+        Order::getStatus,
+        Collectors.counting()
+    ));
+
+// Partition by predicate
+Map<Boolean, List<User>> partitioned = users.stream()
+    .collect(Collectors.partitioningBy(User::isActive));
+
+// To map
+Map<String, User> byId = users.stream()
+    .collect(Collectors.toMap(
+        User::getId,
+        Function.identity(),
+        (existing, replacement) -> existing  // Merge function
+    ));
+
+// Joining strings
+String csv = items.stream()
+    .map(Item::getName)
+    .collect(Collectors.joining(", "));
+
+// Statistics
+IntSummaryStatistics stats = orders.stream()
+    .collect(Collectors.summarizingInt(Order::getQuantity));
+```
+
+## Optional
+
+```java
+// Return Optional for nullable results
+public Optional<User> findById(String id) {
+    return Optional.ofNullable(repository.get(id));
+}
+
+// Chain operations
+String email = findById(id)
+    .filter(User::isActive)
+    .map(User::getEmail)
+    .orElse("unknown@example.com");
+
+// Throw on absence
+User user = findById(id)
+    .orElseThrow(() -> new UserNotFoundException(id));
+
+// Conditional execution
+findById(id).ifPresent(this::sendNotification);
+
+// With fallback computation
+User user = findById(id)
+    .orElseGet(() -> createDefaultUser());
+
+// Stream of Optional (Java 9+)
+List<User> activeUsers = ids.stream()
+    .map(this::findById)
+    .flatMap(Optional::stream)
+    .filter(User::isActive)
+    .toList();
+```
+
+## Best Practices
+
+1. **Prefer immutable collections** from factories (List.of, Set.of, Map.of)
+2. **Size collections** when capacity is known: `new ArrayList<>(100)`
+3. **Use appropriate collection** for use case (HashMap vs TreeMap)
+4. **Avoid null in collections** - use Optional or empty collections
+5. **Stream once** - streams cannot be reused after terminal operation
+6. **Parallel streams carefully** - only for CPU-bound, large datasets
+7. **Optional for returns only** - never as fields or parameters
+
+## References
+
+- [Stream Pipelines](references/stream-pipelines.md) - Advanced stream patterns
+- [Collectors Patterns](references/collectors-patterns.md) - Custom collectors, complex aggregations

package/rules/java/java-collections-streams/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Java Collections & Streams References
+
+## References
+
+- [**Stream Pipelines**](stream-pipelines.md) - Advanced stream operations, lazy evaluation, short-circuiting
+- [**Collectors Patterns**](collectors-patterns.md) - Custom collectors, complex aggregations, downstream collectors
+
+## Quick Checks
+
+- [ ] Use List.of/Set.of/Map.of for immutable collections
+- [ ] Size ArrayList/HashMap when capacity known
+- [ ] Stream once - don't reuse after terminal operation
+- [ ] Parallel streams only for large, CPU-bound operations
+- [ ] Optional for return types, never parameters or fields
+- [ ] Avoid nulls in collections - use empty collections instead

package/rules/java/java-collections-streams/references/collectors-patterns.md

@@ -0,0 +1,178 @@
+# Collectors Patterns
+
+## Built-in Collectors
+
+```java
+// toList, toSet, toCollection
+List<String> list = stream.collect(Collectors.toList());
+Set<String> set = stream.collect(Collectors.toSet());
+TreeSet<String> treeSet = stream.collect(Collectors.toCollection(TreeSet::new));
+
+// Java 16+ shorthand
+List<String> list = stream.toList();  // Returns unmodifiable list
+
+// toMap with merge function
+Map<String, User> userById = users.stream()
+    .collect(Collectors.toMap(
+        User::getId,
+        Function.identity(),
+        (existing, replacement) -> existing,  // Keep existing on duplicate
+        LinkedHashMap::new  // Maintain insertion order
+    ));
+```
+
+## Grouping Collectors
+
+```java
+// Simple groupingBy
+Map<Department, List<Employee>> byDept = employees.stream()
+    .collect(Collectors.groupingBy(Employee::getDepartment));
+
+// With downstream collector
+Map<Department, Long> countByDept = employees.stream()
+    .collect(Collectors.groupingBy(
+        Employee::getDepartment,
+        Collectors.counting()
+    ));
+
+// Nested grouping
+Map<Department, Map<Level, List<Employee>>> nested = employees.stream()
+    .collect(Collectors.groupingBy(
+        Employee::getDepartment,
+        Collectors.groupingBy(Employee::getLevel)
+    ));
+
+// GroupingBy with mapping
+Map<Department, Set<String>> namesByDept = employees.stream()
+    .collect(Collectors.groupingBy(
+        Employee::getDepartment,
+        Collectors.mapping(
+            Employee::getName,
+            Collectors.toSet()
+        )
+    ));
+
+// GroupingBy with reducing
+Map<Department, Optional<Employee>> highestPaid = employees.stream()
+    .collect(Collectors.groupingBy(
+        Employee::getDepartment,
+        Collectors.maxBy(Comparator.comparing(Employee::getSalary))
+    ));
+```
+
+## Partitioning
+
+```java
+// Simple partition
+Map<Boolean, List<User>> partition = users.stream()
+    .collect(Collectors.partitioningBy(User::isActive));
+
+List<User> active = partition.get(true);
+List<User> inactive = partition.get(false);
+
+// Partition with downstream
+Map<Boolean, Long> counts = users.stream()
+    .collect(Collectors.partitioningBy(
+        User::isActive,
+        Collectors.counting()
+    ));
+```
+
+## Aggregation Collectors
+
+```java
+// Statistics
+IntSummaryStatistics stats = orders.stream()
+    .collect(Collectors.summarizingInt(Order::getQuantity));
+// stats.getSum(), stats.getAverage(), stats.getMax(), stats.getMin(), stats.getCount()
+
+// Sum with mapping
+int totalQuantity = orders.stream()
+    .collect(Collectors.summingInt(Order::getQuantity));
+
+// Average
+Double avgSalary = employees.stream()
+    .collect(Collectors.averagingDouble(Employee::getSalary));
+
+// Max/Min
+Optional<Employee> highest = employees.stream()
+    .collect(Collectors.maxBy(Comparator.comparing(Employee::getSalary)));
+```
+
+## Joining Collector
+
+```java
+// Simple join
+String csv = names.stream()
+    .collect(Collectors.joining(", "));
+
+// With prefix and suffix
+String json = items.stream()
+    .map(Item::toJson)
+    .collect(Collectors.joining(",\n", "[\n", "\n]"));
+```
+
+## Custom Collectors
+
+```java
+// Collector.of pattern
+Collector<Person, ?, ImmutableList<Person>> toImmutableList =
+    Collector.of(
+        ImmutableList::<Person>builder,           // Supplier
+        ImmutableList.Builder::add,               // Accumulator
+        (b1, b2) -> b1.addAll(b2.build()),       // Combiner
+        ImmutableList.Builder::build              // Finisher
+    );
+
+// Using collectingAndThen for transformation
+List<User> unmodifiable = users.stream()
+    .collect(Collectors.collectingAndThen(
+        Collectors.toList(),
+        Collections::unmodifiableList
+    ));
+
+// Teeing collector (Java 12+) - two collectors at once
+record MinMax(int min, int max) {}
+
+MinMax result = numbers.stream()
+    .collect(Collectors.teeing(
+        Collectors.minBy(Comparator.naturalOrder()),
+        Collectors.maxBy(Comparator.naturalOrder()),
+        (min, max) -> new MinMax(
+            min.orElse(0),
+            max.orElse(0)
+        )
+    ));
+```
+
+## Filtering Collector (Java 9+)
+
+```java
+// Filter within grouping
+Map<Department, List<Employee>> seniorByDept = employees.stream()
+    .collect(Collectors.groupingBy(
+        Employee::getDepartment,
+        Collectors.filtering(
+            e -> e.getYearsOfService() > 5,
+            Collectors.toList()
+        )
+    ));
+
+// vs filter before grouping (different semantics)
+// filtering: includes all departments, even with empty lists
+// filter: excludes departments with no matching employees
+```
+
+## FlatMapping Collector (Java 9+)
+
+```java
+// FlatMap within grouping
+Map<Author, Set<String>> tagsByAuthor = posts.stream()
+    .collect(Collectors.groupingBy(
+        Post::getAuthor,
+        Collectors.flatMapping(
+            post -> post.getTags().stream(),
+            Collectors.toSet()
+        )
+    ));
+```