@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/golang/zap-logging/references/logger-config.md

@@ -0,0 +1,165 @@
+# Zap Logger Configuration
+
+## Basic Setup
+
+```go
+import "go.uber.org/zap"
+
+func main() {
+    // Development (human-readable, debug level)
+    logger, _ := zap.NewDevelopment()
+    defer logger.Sync()
+
+    // Production (JSON, info level)
+    logger, _ := zap.NewProduction()
+    defer logger.Sync()
+
+    // Example logger (for tests)
+    logger := zap.NewExample()
+}
+```
+
+## Standard Logger
+
+```go
+logger, _ := zap.NewProduction()
+
+// Typed fields - fast, type-safe
+logger.Info("user logged in",
+    zap.String("user_id", "12345"),
+    zap.Int("attempt", 1),
+    zap.Duration("latency", time.Second),
+    zap.Time("timestamp", time.Now()),
+    zap.Any("metadata", map[string]string{"key": "value"}),
+)
+
+logger.Error("failed to process",
+    zap.Error(err),
+    zap.String("request_id", reqID),
+)
+
+// Log levels
+logger.Debug("debug message")
+logger.Info("info message")
+logger.Warn("warning message")
+logger.Error("error message")
+logger.Fatal("fatal - calls os.Exit(1)")
+logger.Panic("panic - calls panic()")
+```
+
+## Sugared Logger
+
+```go
+logger, _ := zap.NewProduction()
+sugar := logger.Sugar()
+defer sugar.Sync()
+
+// Printf-style (slower but convenient)
+sugar.Infof("user %s logged in", userID)
+sugar.Errorw("failed to process",
+    "error", err,
+    "request_id", reqID,
+)
+
+// Key-value pairs
+sugar.Infow("user action",
+    "user_id", userID,
+    "action", "login",
+    "ip", clientIP,
+)
+```
+
+## Custom Configuration
+
+```go
+config := zap.Config{
+    Level:       zap.NewAtomicLevelAt(zap.InfoLevel),
+    Development: false,
+    Encoding:    "json", // or "console"
+    EncoderConfig: zapcore.EncoderConfig{
+        TimeKey:        "timestamp",
+        LevelKey:       "level",
+        NameKey:        "logger",
+        CallerKey:      "caller",
+        MessageKey:     "message",
+        StacktraceKey:  "stacktrace",
+        LineEnding:     zapcore.DefaultLineEnding,
+        EncodeLevel:    zapcore.LowercaseLevelEncoder,
+        EncodeTime:     zapcore.ISO8601TimeEncoder,
+        EncodeDuration: zapcore.MillisDurationEncoder,
+        EncodeCaller:   zapcore.ShortCallerEncoder,
+    },
+    OutputPaths:      []string{"stdout", "/var/log/app.log"},
+    ErrorOutputPaths: []string{"stderr"},
+}
+
+logger, _ := config.Build()
+```
+
+## Child Loggers
+
+```go
+logger, _ := zap.NewProduction()
+
+// Add fields to all subsequent logs
+requestLogger := logger.With(
+    zap.String("request_id", uuid.New().String()),
+    zap.String("user_id", userID),
+)
+
+requestLogger.Info("processing request")
+requestLogger.Info("request completed") // includes request_id and user_id
+```
+
+## Sampling (High-Volume)
+
+```go
+config := zap.NewProductionConfig()
+config.Sampling = &zap.SamplingConfig{
+    Initial:    100,  // log first 100 per second
+    Thereafter: 100,  // then log every 100th
+}
+
+logger, _ := config.Build()
+```
+
+## Integration with Gin/Echo
+
+```go
+// Gin middleware
+func GinLogger(logger *zap.Logger) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        start := time.Now()
+        path := c.Request.URL.Path
+
+        c.Next()
+
+        logger.Info("request",
+            zap.String("path", path),
+            zap.String("method", c.Request.Method),
+            zap.Int("status", c.Writer.Status()),
+            zap.Duration("latency", time.Since(start)),
+        )
+    }
+}
+
+// Echo middleware
+func EchoLogger(logger *zap.Logger) echo.MiddlewareFunc {
+    return func(next echo.HandlerFunc) echo.HandlerFunc {
+        return func(c echo.Context) error {
+            start := time.Now()
+            
+            err := next(c)
+            
+            logger.Info("request",
+                zap.String("path", c.Path()),
+                zap.String("method", c.Request().Method),
+                zap.Int("status", c.Response().Status),
+                zap.Duration("latency", time.Since(start)),
+            )
+            
+            return err
+        }
+    }
+}
+```

package/rules/java/build-gradle/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: Gradle Build
+description: Kotlin DSL, dependencies, tasks, plugins, and multi-project builds.
+metadata:
+  labels: [java, gradle, build]
+  triggers:
+    files: ['build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts']
+    keywords: [dependencies, plugins, tasks, implementation, testImplementation, kotlin]
+---
+
+# Gradle Build Standards
+
+## Kotlin DSL Structure
+
+```kotlin
+// build.gradle.kts
+plugins {
+    java
+    id("org.springframework.boot") version "3.2.0"
+    id("io.spring.dependency-management") version "1.1.4"
+}
+
+group = "com.example"
+version = "1.0.0-SNAPSHOT"
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
+    runtimeOnly("org.postgresql:postgresql")
+
+    testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+```
+
+## Dependency Configurations
+
+```kotlin
+dependencies {
+    implementation("...")       // Compile + runtime, not exposed
+    api("...")                  // Compile + runtime, exposed to consumers
+    compileOnly("...")          // Compile only (like Lombok)
+    runtimeOnly("...")          // Runtime only (JDBC drivers)
+    testImplementation("...")   // Test compile + runtime
+    annotationProcessor("...")  // Annotation processing
+}
+```
+
+## Custom Tasks
+
+```kotlin
+tasks.register("hello") {
+    group = "custom"
+    description = "Prints hello"
+    doLast {
+        println("Hello, Gradle!")
+    }
+}
+
+tasks.register<Copy>("copyResources") {
+    from("src/main/resources")
+    into("build/resources")
+}
+```
+
+## Common Commands
+
+```bash
+./gradlew build          # Build project
+./gradlew test           # Run tests
+./gradlew bootRun        # Run Spring Boot
+./gradlew dependencies   # Show dependencies
+./gradlew tasks          # List tasks
+```
+
+## References
+
+- [Kotlin DSL](references/kotlin-dsl.md) - Migration from Groovy, type-safe configuration

package/rules/java/build-gradle/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Gradle Build References
+
+## References
+
+- [**Kotlin DSL**](kotlin-dsl.md) - Build scripts, version catalogs, multi-project
+- [**Task Configuration**](task-configuration.md) - Task types, dependencies, caching
+
+## Quick Checks
+
+- [ ] Use Kotlin DSL for type-safe builds
+- [ ] Version catalogs for centralized dependencies
+- [ ] Lazy task configuration with register()
+- [ ] Enable build cache for faster builds
+- [ ] Use configuration avoidance APIs

package/rules/java/build-gradle/references/kotlin-dsl.md

@@ -0,0 +1,118 @@
+# Gradle Kotlin DSL
+
+## Basic Build Script
+
+```kotlin
+// build.gradle.kts
+plugins {
+    java
+    id("org.springframework.boot") version "3.2.0"
+    id("io.spring.dependency-management") version "1.1.4"
+}
+
+group = "com.example"
+version = "1.0.0"
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_21
+    targetCompatibility = JavaVersion.VERSION_21
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
+    
+    runtimeOnly("org.postgresql:postgresql")
+    
+    compileOnly("org.projectlombok:lombok")
+    annotationProcessor("org.projectlombok:lombok")
+    
+    testImplementation("org.springframework.boot:spring-boot-starter-test")
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+```
+
+## Version Catalogs
+
+```toml
+# gradle/libs.versions.toml
+[versions]
+spring-boot = "3.2.0"
+lombok = "1.18.30"
+junit = "5.10.0"
+
+[libraries]
+spring-boot-web = { module = "org.springframework.boot:spring-boot-starter-web" }
+spring-boot-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa" }
+lombok = { module = "org.projectlombok:lombok", version.ref = "lombok" }
+junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
+
+[plugins]
+spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
+```
+
+```kotlin
+// build.gradle.kts
+plugins {
+    alias(libs.plugins.spring.boot)
+}
+
+dependencies {
+    implementation(libs.spring.boot.web)
+    implementation(libs.spring.boot.jpa)
+    compileOnly(libs.lombok)
+    testImplementation(libs.junit.jupiter)
+}
+```
+
+## Custom Tasks
+
+```kotlin
+tasks.register<Copy>("copyDocs") {
+    from("docs")
+    into(layout.buildDirectory.dir("documentation"))
+}
+
+tasks.named("build") {
+    dependsOn("copyDocs")
+}
+
+// Task with typed configuration
+tasks.register<Jar>("sourcesJar") {
+    archiveClassifier.set("sources")
+    from(sourceSets.main.get().allSource)
+}
+```
+
+## Multi-Project Builds
+
+```kotlin
+// settings.gradle.kts
+rootProject.name = "my-project"
+include("core", "api", "web")
+
+// root build.gradle.kts
+subprojects {
+    apply(plugin = "java")
+    
+    repositories {
+        mavenCentral()
+    }
+    
+    dependencies {
+        testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
+    }
+}
+
+// api/build.gradle.kts
+dependencies {
+    implementation(project(":core"))
+}
+```

package/rules/java/build-gradle/references/task-configuration.md

@@ -0,0 +1,132 @@
+# Gradle Task Configuration
+
+## Task Types
+
+```kotlin
+// Copy task
+tasks.register<Copy>("copyResources") {
+    from("src/main/resources")
+    into(layout.buildDirectory.dir("resources"))
+    include("**/*.properties")
+    exclude("**/test-*")
+}
+
+// Exec task
+tasks.register<Exec>("runScript") {
+    commandLine("bash", "-c", "echo Hello")
+    workingDir = projectDir
+}
+
+// Delete task
+tasks.register<Delete>("cleanGenerated") {
+    delete(layout.buildDirectory.dir("generated"))
+}
+
+// Zip task
+tasks.register<Zip>("createDist") {
+    from(layout.buildDirectory.dir("libs"))
+    archiveFileName.set("dist-${project.version}.zip")
+    destinationDirectory.set(layout.buildDirectory.dir("distributions"))
+}
+```
+
+## Task Dependencies
+
+```kotlin
+tasks.register("prepare") {
+    doLast { println("Preparing...") }
+}
+
+tasks.register("build") {
+    dependsOn("prepare")
+    doLast { println("Building...") }
+}
+
+tasks.register("deploy") {
+    mustRunAfter("build")
+    doLast { println("Deploying...") }
+}
+
+// Finalized by
+tasks.named("build") {
+    finalizedBy("report")
+}
+```
+
+## Lazy Configuration
+
+```kotlin
+// Lazy property
+val outputDir = objects.directoryProperty()
+outputDir.set(layout.buildDirectory.dir("output"))
+
+tasks.register<Copy>("copyOutput") {
+    from(tasks.named("compile"))
+    into(outputDir)
+}
+
+// Provider API
+val jarFile = tasks.named<Jar>("jar").flatMap { it.archiveFile }
+
+tasks.register("printJar") {
+    doLast {
+        println("JAR: ${jarFile.get().asFile}")
+    }
+}
+```
+
+## Task Avoidance
+
+```kotlin
+// DON'T - eagerly creates task
+tasks.create("eagerTask") { }
+
+// DO - lazily creates task
+tasks.register("lazyTask") { }
+
+// Configure existing task lazily
+tasks.named<Test>("test") {
+    useJUnitPlatform()
+    maxParallelForks = Runtime.getRuntime().availableProcessors()
+}
+```
+
+## Build Cache
+
+```kotlin
+// Enable in gradle.properties
+// org.gradle.caching=true
+
+tasks.register("cachedTask") {
+    inputs.files("src/main/resources")
+    outputs.dir(layout.buildDirectory.dir("cached"))
+    
+    outputs.cacheIf { true }
+    
+    doLast {
+        // Task action
+    }
+}
+```
+
+## Common Commands
+
+```bash
+# List tasks
+./gradlew tasks
+
+# Run with info
+./gradlew build --info
+
+# Skip tests
+./gradlew build -x test
+
+# Parallel execution
+./gradlew build --parallel
+
+# Refresh dependencies
+./gradlew build --refresh-dependencies
+
+# Build scan
+./gradlew build --scan
+```

package/rules/java/build-maven/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: Maven Build
+description: POM structure, dependency management, plugins, profiles, and multi-module projects.
+metadata:
+  labels: [java, maven, build]
+  triggers:
+    files: ['pom.xml']
+    keywords: [dependencyManagement, plugin, maven, lifecycle, groupId, artifactId, version]
+---
+
+# Maven Build Standards
+
+## POM Structure
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <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>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+```
+
+## Dependency Management
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <!-- BOM import -->
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-dependencies</artifactId>
+            <version>2023.0.0</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+## Common Commands
+
+```bash
+mvn clean install              # Build and install
+mvn clean install -DskipTests  # Skip tests
+mvn dependency:tree            # Show dependency tree
+mvn versions:display-dependency-updates  # Check updates
+mvn spring-boot:run            # Run Spring Boot app
+```
+
+## References
+
+- [Dependency Management](references/dependency-management.md) - BOMs, exclusions, versions

package/rules/java/build-maven/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Maven Build References
+
+## References
+
+- [**Lifecycle Phases**](lifecycle-phases.md) - Build phases, plugin configuration, multi-module
+- [**Dependency Management**](dependency-management.md) - Scopes, BOM, exclusions, versions
+
+## Quick Checks
+
+- [ ] Use appropriate dependency scopes
+- [ ] Centralize versions in properties or BOM
+- [ ] Configure compiler for target Java version
+- [ ] Use Surefire for unit tests, Failsafe for integration
+- [ ] Profile-based builds for environments