@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/java/java-project-structure/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: Java Project Structure
+description: Standard project layout, package conventions, module system, and layered architecture patterns.
+metadata:
+  labels: [java, project, architecture, structure]
+  triggers:
+    files: ['pom.xml', 'build.gradle', 'build.gradle.kts', 'settings.gradle', 'module-info.java']
+    keywords: [src/main/java, src/test/java, module-info, package, module]
+---
+
+# Java Project Structure Standards
+
+## Standard Maven/Gradle Layout
+
+```
+project-root/
+├── src/
+│   ├── main/
+│   │   ├── java/           # Application source code
+│   │   │   └── com/example/app/
+│   │   │       ├── Application.java
+│   │   │       ├── config/
+│   │   │       ├── controller/
+│   │   │       ├── service/
+│   │   │       ├── repository/
+│   │   │       ├── model/
+│   │   │       └── exception/
+│   │   └── resources/      # Configuration files
+│   │       ├── application.yml
+│   │       ├── application-dev.yml
+│   │       ├── application-prod.yml
+│   │       └── db/migration/
+│   └── test/
+│       ├── java/           # Test source code
+│       │   └── com/example/app/
+│       │       ├── controller/
+│       │       ├── service/
+│       │       └── repository/
+│       └── resources/      # Test resources
+│           └── application-test.yml
+├── pom.xml                 # Maven build
+├── build.gradle.kts        # or Gradle build
+└── README.md
+```
+
+## Package Naming Conventions
+
+```java
+// Reverse domain name + project + layer
+com.company.project.controller
+com.company.project.service
+com.company.project.repository
+com.company.project.model
+com.company.project.dto
+com.company.project.exception
+com.company.project.config
+com.company.project.util
+
+// Feature-based alternative
+com.company.project.user.controller
+com.company.project.user.service
+com.company.project.order.controller
+com.company.project.order.service
+```
+
+## Layered Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           Controller Layer              │  ← HTTP handling, validation
+├─────────────────────────────────────────┤
+│            Service Layer                │  ← Business logic
+├─────────────────────────────────────────┤
+│          Repository Layer               │  ← Data access
+├─────────────────────────────────────────┤
+│           Model/Entity                  │  ← Domain objects
+└─────────────────────────────────────────┘
+
+// Dependency rules:
+// Controller → Service → Repository → Model
+// NEVER: Repository → Service or Model → anything
+```
+
+```java
+// Controller - handles HTTP
+@RestController
+@RequestMapping("/api/users")
+public class UserController {
+    private final UserService userService;
+    // Only UserService, never UserRepository
+}
+
+// Service - business logic
+@Service
+public class UserService {
+    private final UserRepository userRepository;
+    private final EmailService emailService;
+    // Can use multiple repositories and services
+}
+
+// Repository - data access
+@Repository
+public interface UserRepository extends JpaRepository<User, Long> {
+    // Only data operations
+}
+```
+
+## DTO Pattern
+
+```java
+// Separate DTOs for request/response
+public record CreateUserRequest(
+    @NotBlank String name,
+    @Email String email
+) {}
+
+public record UserResponse(
+    Long id,
+    String name,
+    String email,
+    LocalDateTime createdAt
+) {
+    public static UserResponse from(User user) {
+        return new UserResponse(
+            user.getId(),
+            user.getName(),
+            user.getEmail(),
+            user.getCreatedAt()
+        );
+    }
+}
+
+// Mapper interface
+public interface UserMapper {
+    User toEntity(CreateUserRequest request);
+    UserResponse toResponse(User user);
+}
+```
+
+## Module System (JPMS)
+
+```java
+// module-info.java
+module com.example.app {
+    // Dependencies
+    requires java.sql;
+    requires spring.boot;
+    requires spring.boot.autoconfigure;
+    requires spring.web;
+
+    // What we export
+    exports com.example.app.api;
+    exports com.example.app.model;
+
+    // Internal packages (not exported)
+    // com.example.app.internal is hidden
+
+    // Reflection access for frameworks
+    opens com.example.app.model to spring.core;
+    opens com.example.app to spring.beans;
+}
+```
+
+## Multi-Module Project
+
+```
+parent-project/
+├── pom.xml                    # Parent POM
+├── core/                      # Shared domain, utils
+│   ├── pom.xml
+│   └── src/main/java/
+├── api/                       # REST API module
+│   ├── pom.xml
+│   └── src/main/java/
+├── service/                   # Business logic
+│   ├── pom.xml
+│   └── src/main/java/
+└── infrastructure/            # External integrations
+    ├── pom.xml
+    └── src/main/java/
+```
+
+## Best Practices
+
+1. **One class per file** - class name matches file name
+2. **Package by layer OR feature** - pick one, be consistent
+3. **Keep packages flat** - avoid deep nesting
+4. **Separate DTOs from entities** - never expose entities in API
+5. **module-info.java** for libraries, optional for applications
+6. **Resources alongside code** - feature-specific configs with feature
+
+## References
+
+- [Maven Project Layout](references/maven-project-layout.md) - Complete structure, profiles
+- [Module System](references/module-system.md) - JPMS patterns, migration

package/rules/java/java-project-structure/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Java Project Structure References
+
+## References
+
+- [**Maven Project Layout**](maven-project-layout.md) - Standard directories, profiles, multi-module setup
+- [**Module System**](module-system.md) - JPMS patterns, exports, opens, migration from classpath
+
+## Quick Checks
+
+- [ ] Standard Maven/Gradle layout (src/main/java, src/test/java)
+- [ ] Reverse domain package naming (com.company.project.layer)
+- [ ] Layer dependencies flow downward only
+- [ ] DTOs separate from entities
+- [ ] Test packages mirror source packages
+- [ ] Configuration in src/main/resources

package/rules/java/java-project-structure/references/maven-project-layout.md

@@ -0,0 +1,199 @@
+# Maven Project Layout
+
+## Standard Directory Structure
+
+```
+project/
+├── pom.xml
+├── src/
+│   ├── main/
+│   │   ├── java/                    # Java source files
+│   │   ├── resources/               # Resources bundled in JAR
+│   │   │   ├── application.yml
+│   │   │   ├── logback.xml
+│   │   │   └── META-INF/
+│   │   └── filters/                 # Resource filter files
+│   └── test/
+│       ├── java/                    # Test source files
+│       └── resources/               # Test resources
+│           └── application-test.yml
+├── target/                          # Build output (generated)
+└── .mvn/                            # Maven wrapper
+    └── wrapper/
+        └── maven-wrapper.properties
+```
+
+## POM Structure
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.2.0</version>
+    </parent>
+
+    <groupId>com.example</groupId>
+    <artifactId>my-app</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+
+    <properties>
+        <java.version>21</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+    <profiles>
+        <profile>
+            <id>dev</id>
+            <activation>
+                <activeByDefault>true</activeByDefault>
+            </activation>
+            <properties>
+                <spring.profiles.active>dev</spring.profiles.active>
+            </properties>
+        </profile>
+        <profile>
+            <id>prod</id>
+            <properties>
+                <spring.profiles.active>prod</spring.profiles.active>
+            </properties>
+        </profile>
+    </profiles>
+</project>
+```
+
+## Multi-Module Project
+
+```
+parent/
+├── pom.xml                 # Parent POM
+├── common/
+│   ├── pom.xml
+│   └── src/main/java/
+├── api/
+│   ├── pom.xml
+│   └── src/main/java/
+└── service/
+    ├── pom.xml
+    └── src/main/java/
+```
+
+**Parent POM:**
+
+```xml
+<project>
+    <groupId>com.example</groupId>
+    <artifactId>parent</artifactId>
+    <version>1.0.0</version>
+    <packaging>pom</packaging>
+
+    <modules>
+        <module>common</module>
+        <module>api</module>
+        <module>service</module>
+    </modules>
+
+    <dependencyManagement>
+        <dependencies>
+            <!-- Shared dependency versions -->
+            <dependency>
+                <groupId>com.example</groupId>
+                <artifactId>common</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+</project>
+```
+
+**Child POM:**
+
+```xml
+<project>
+    <parent>
+        <groupId>com.example</groupId>
+        <artifactId>parent</artifactId>
+        <version>1.0.0</version>
+    </parent>
+
+    <artifactId>api</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.example</groupId>
+            <artifactId>common</artifactId>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+## Resource Filtering
+
+```xml
+<!-- pom.xml -->
+<build>
+    <resources>
+        <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+        </resource>
+    </resources>
+</build>
+```
+
+```yaml
+# application.yml
+app:
+  version: @project.version@
+  build-time: @maven.build.timestamp@
+```
+
+## Common Commands
+
+```bash
+# Build
+mvn clean install
+
+# Skip tests
+mvn clean install -DskipTests
+
+# Run specific profile
+mvn clean install -Pprod
+
+# Dependency tree
+mvn dependency:tree
+
+# Effective POM
+mvn help:effective-pom
+
+# Update versions
+mvn versions:set -DnewVersion=2.0.0
+
+# Check for dependency updates
+mvn versions:display-dependency-updates
+```

package/rules/java/java-project-structure/references/module-system.md

@@ -0,0 +1,159 @@
+# Java Module System (JPMS)
+
+## Module Declaration
+
+```java
+// src/main/java/module-info.java
+module com.example.myapp {
+    // Required modules (dependencies)
+    requires java.base;           // Implicit, always available
+    requires java.sql;            // JDK module
+    requires java.logging;
+    requires spring.boot;         // Third-party module
+    requires spring.web;
+    requires transitive com.example.common;  // Transitive dependency
+
+    // Exported packages (public API)
+    exports com.example.myapp.api;
+    exports com.example.myapp.model;
+    exports com.example.myapp.dto to com.example.client;  // Qualified export
+
+    // Opened packages (for reflection)
+    opens com.example.myapp.model to spring.core, hibernate.core;
+    opens com.example.myapp to spring.beans;
+
+    // Service provider
+    provides com.example.spi.PaymentProcessor
+        with com.example.myapp.StripeProcessor;
+
+    // Service consumer
+    uses com.example.spi.NotificationService;
+}
+```
+
+## Module Keywords
+
+```java
+// requires - declare dependency
+requires java.sql;                    // Regular dependency
+requires transitive spring.core;      // Transitive (consumers get it too)
+requires static lombok;               // Optional (compile-time only)
+
+// exports - make packages accessible
+exports com.example.api;              // Export to all
+exports com.example.internal to com.example.test;  // Qualified export
+
+// opens - allow reflection
+opens com.example.model;              // Open to all for reflection
+opens com.example.entity to hibernate.core;  // Qualified open
+
+// open module - everything open for reflection
+open module com.example.app {
+    requires spring.boot;
+    exports com.example.api;
+}
+```
+
+## Automatic Modules
+
+For JARs without module-info.java (most legacy libraries):
+
+```java
+// Module name derived from JAR filename or Automatic-Module-Name manifest
+// guava-31.1-jre.jar → guava
+// commons-lang3-3.12.0.jar → commons.lang3
+
+module com.example.app {
+    requires guava;         // Automatic module
+    requires commons.lang3; // Automatic module
+}
+```
+
+**Manifest entry (recommended for libraries):**
+```
+Automatic-Module-Name: com.google.guava
+```
+
+## Module Path vs Class Path
+
+```bash
+# Module path (JPMS)
+java --module-path mods -m com.example.app/com.example.Main
+
+# Class path (traditional)
+java -cp "lib/*:app.jar" com.example.Main
+
+# Mixed (automatic modules on module path)
+java --module-path mods --add-modules ALL-MODULE-PATH -cp legacy.jar com.example.Main
+```
+
+## Migration Strategy
+
+### 1. Bottom-up Migration
+
+```
+1. Identify leaf modules (no internal dependencies)
+2. Add module-info.java to leaf modules
+3. Move up the dependency tree
+4. Use automatic modules for unmigrated dependencies
+```
+
+### 2. Handling Reflection
+
+```java
+// Spring/Hibernate need reflection access
+module com.example.app {
+    // Open specific packages
+    opens com.example.entity to hibernate.core;
+    opens com.example.config to spring.core;
+
+    // Or open entire module
+    // open module com.example.app { ... }
+}
+```
+
+### 3. Split Packages
+
+```java
+// PROBLEM: Same package in multiple JARs
+// javax.annotation in jsr305.jar AND java.annotation module
+
+// SOLUTION: Exclude duplicate JAR or merge packages
+// In Maven: use <exclusions>
+```
+
+## Compile and Run
+
+```bash
+# Compile
+javac -d out --module-source-path src $(find src -name "*.java")
+
+# Package
+jar --create --file mods/com.example.app.jar \
+    --main-class com.example.Main \
+    -C out/com.example.app .
+
+# Run
+java --module-path mods -m com.example.app
+
+# With VM args
+java --module-path mods \
+     --add-opens java.base/java.lang=com.example.app \
+     -m com.example.app
+```
+
+## Debugging Module Issues
+
+```bash
+# Show module resolution
+java --show-module-resolution -m com.example.app
+
+# Describe module
+jar --describe-module --file=app.jar
+
+# List modules
+java --list-modules
+
+# Check for split packages
+jdeps --multi-release 21 -s app.jar
+```

package/rules/java/micronaut-core/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: Micronaut Core
+description: Compile-time dependency injection, configuration, AOP, and startup optimization.
+metadata:
+  labels: [java, micronaut, di, aot]
+  triggers:
+    files: ['**/*.java', 'application.yml', 'application.properties']
+    keywords: [Micronaut, '@Inject', '@Singleton', '@ConfigurationProperties', '@Factory', '@Controller']
+---
+
+# Micronaut Core Standards
+
+## Compile-Time DI
+
+```java
+@Singleton
+public class UserService {
+
+    private final UserRepository repository;
+    private final EventPublisher eventPublisher;
+
+    // Constructor injection (preferred)
+    public UserService(UserRepository repository, EventPublisher eventPublisher) {
+        this.repository = repository;
+        this.eventPublisher = eventPublisher;
+    }
+}
+
+// Factory beans
+@Factory
+public class ClientFactory {
+
+    @Singleton
+    @Named("primary")
+    public HttpClient primaryClient() {
+        return HttpClient.create(URI.create("https://api.primary.com"));
+    }
+
+    @Singleton
+    @Named("fallback")
+    public HttpClient fallbackClient() {
+        return HttpClient.create(URI.create("https://api.fallback.com"));
+    }
+}
+```
+
+## Configuration
+
+```java
+@ConfigurationProperties("app")
+public record AppConfig(
+    String name,
+    int maxConnections,
+    DatabaseConfig database
+) {
+    public record DatabaseConfig(
+        String url,
+        String username
+    ) {}
+}
+```
+
+```yaml
+app:
+  name: MyMicronautApp
+  max-connections: 100
+  database:
+    url: jdbc:postgresql://localhost/db
+    username: admin
+```
+
+## Controllers
+
+```java
+@Controller("/users")
+public class UserController {
+
+    private final UserService userService;
+
+    public UserController(UserService userService) {
+        this.userService = userService;
+    }
+
+    @Get("/{id}")
+    public User findById(Long id) {
+        return userService.findById(id);
+    }
+
+    @Post
+    @Status(HttpStatus.CREATED)
+    public User create(@Valid @Body CreateUserRequest request) {
+        return userService.create(request);
+    }
+}
+```
+
+## References
+
+- [Compile-Time DI](references/compile-time-di.md) - AOT benefits, introspection

package/rules/java/micronaut-core/references/REFERENCE.md

@@ -0,0 +1,12 @@
+# Micronaut Core References
+
+## References
+
+- [**Compile-Time DI**](compile-time-di.md) - AOT benefits, bean introspection, startup time
+
+## Quick Checks
+
+- [ ] Use @Singleton for services
+- [ ] Constructor injection over field injection
+- [ ] Use records for configuration properties
+- [ ] No reflection - everything at compile time