@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/golang/wire-di/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: Wire Dependency Injection
+description: Compile-time dependency injection from Google.
+metadata:
+  labels: [golang, wire, di, dependency-injection]
+  triggers:
+    files: ['**/wire.go', '**/wire_gen.go']
+    keywords: [wire, Build, NewSet, Bind, Injector]
+---
+
+# Wire DI Standards
+
+## Basic Setup
+
+```go
+// wire.go
+//go:build wireinject
+// +build wireinject
+
+package main
+
+import "github.com/google/wire"
+
+func InitializeApp() (*App, error) {
+    wire.Build(
+        NewDatabase,
+        NewUserRepository,
+        NewUserService,
+        NewApp,
+    )
+    return nil, nil
+}
+```
+
+```bash
+# Generate wire_gen.go
+wire ./...
+```
+
+## Providers
+
+```go
+// Providers are constructors
+func NewDatabase(cfg *Config) (*sql.DB, error) {
+    return sql.Open("postgres", cfg.DatabaseURL)
+}
+
+func NewUserRepository(db *sql.DB) *UserRepository {
+    return &UserRepository{db: db}
+}
+
+func NewUserService(repo *UserRepository) *UserService {
+    return &UserService{repo: repo}
+}
+
+func NewApp(svc *UserService) *App {
+    return &App{userService: svc}
+}
+```
+
+## Provider Sets
+
+```go
+// Group related providers
+var DatabaseSet = wire.NewSet(
+    NewDatabase,
+    NewUserRepository,
+    NewPostRepository,
+)
+
+var ServiceSet = wire.NewSet(
+    NewUserService,
+    NewPostService,
+)
+
+// Use sets in injector
+func InitializeApp(cfg *Config) (*App, error) {
+    wire.Build(
+        DatabaseSet,
+        ServiceSet,
+        NewApp,
+    )
+    return nil, nil
+}
+```
+
+## Interface Binding
+
+```go
+type UserRepository interface {
+    FindByID(id int) (*User, error)
+}
+
+type userRepository struct {
+    db *sql.DB
+}
+
+func NewUserRepository(db *sql.DB) *userRepository {
+    return &userRepository{db: db}
+}
+
+// Bind implementation to interface
+var RepositorySet = wire.NewSet(
+    NewUserRepository,
+    wire.Bind(new(UserRepository), new(*userRepository)),
+)
+```
+
+## Struct Providers
+
+```go
+type Config struct {
+    DatabaseURL string
+    Port        int
+}
+
+// Provide struct fields
+var ConfigSet = wire.NewSet(
+    wire.Struct(new(Config), "*"), // All fields
+    // or
+    wire.Struct(new(Config), "DatabaseURL", "Port"), // Specific fields
+)
+
+// Field providers must exist
+func InitializeApp(dbURL string, port int) (*App, error) {
+    wire.Build(
+        ConfigSet,
+        // ...
+    )
+    return nil, nil
+}
+```
+
+## Value Providers
+
+```go
+func InitializeApp() (*App, error) {
+    wire.Build(
+        wire.Value(&Config{
+            DatabaseURL: "postgres://...",
+            Port:        8080,
+        }),
+        NewDatabase,
+        NewApp,
+    )
+    return nil, nil
+}
+
+// Or interface value
+wire.InterfaceValue(new(io.Writer), os.Stdout)
+```
+
+## Cleanup Functions
+
+```go
+func NewDatabase(cfg *Config) (*sql.DB, func(), error) {
+    db, err := sql.Open("postgres", cfg.DatabaseURL)
+    if err != nil {
+        return nil, nil, err
+    }
+
+    cleanup := func() {
+        db.Close()
+    }
+
+    return db, cleanup, nil
+}
+
+// Injector returns cleanup
+func InitializeApp(cfg *Config) (*App, func(), error) {
+    wire.Build(
+        NewDatabase,
+        NewApp,
+    )
+    return nil, nil, nil
+}
+
+// Usage
+app, cleanup, err := InitializeApp(cfg)
+if err != nil {
+    log.Fatal(err)
+}
+defer cleanup()
+```
+
+## Multiple Injectors
+
+```go
+// wire.go
+//go:build wireinject
+
+package main
+
+import "github.com/google/wire"
+
+// For HTTP server
+func InitializeHTTPServer(cfg *Config) (*HTTPServer, func(), error) {
+    wire.Build(
+        DatabaseSet,
+        HTTPSet,
+    )
+    return nil, nil, nil
+}
+
+// For CLI
+func InitializeCLI(cfg *Config) (*CLI, error) {
+    wire.Build(
+        DatabaseSet,
+        CLISet,
+    )
+    return nil, nil
+}
+```
+
+## Testing
+
+```go
+// Mock for testing
+type mockUserRepository struct{}
+
+func (m *mockUserRepository) FindByID(id int) (*User, error) {
+    return &User{ID: id, Name: "Test"}, nil
+}
+
+// Test injector
+func InitializeTestApp() (*App, error) {
+    wire.Build(
+        wire.Value(&mockUserRepository{}),
+        wire.Bind(new(UserRepository), new(*mockUserRepository)),
+        NewUserService,
+        NewApp,
+    )
+    return nil, nil
+}
+```
+
+## Best Practices
+
+1. **Provider sets**: Group related providers
+2. **Interfaces**: Use `wire.Bind` for testability
+3. **Cleanup**: Return cleanup functions for resources
+4. **Build tags**: Use `wireinject` build tag
+5. **Regenerate**: Run `wire ./...` after changes

package/rules/golang/wire-di/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Wire DI References
+
+## References
+
+- [**Provider Patterns**](provider-patterns.md) - Providers, sets, injectors
+
+## Quick Checks
+
+- [ ] Use ProviderSet for grouping related providers
+- [ ] wire.Build in injector functions
+- [ ] Interface bindings with wire.Bind
+- [ ] Cleanup functions for resources
+- [ ] Run wire generate after changes

package/rules/golang/wire-di/references/provider-patterns.md

@@ -0,0 +1,193 @@
+# Wire Provider Patterns
+
+## Basic Providers
+
+```go
+// Provider function returns a dependency
+func NewDatabase(cfg *Config) (*Database, error) {
+    db, err := sql.Open("postgres", cfg.DSN)
+    if err != nil {
+        return nil, err
+    }
+    return &Database{db: db}, nil
+}
+
+func NewUserRepository(db *Database) *UserRepository {
+    return &UserRepository{db: db}
+}
+
+func NewUserService(repo *UserRepository) *UserService {
+    return &UserService{repo: repo}
+}
+```
+
+## Injector Function
+
+```go
+// +build wireinject
+
+package main
+
+import "github.com/google/wire"
+
+// InitializeApp creates the application with all dependencies
+func InitializeApp(cfg *Config) (*App, error) {
+    wire.Build(
+        NewDatabase,
+        NewUserRepository,
+        NewUserService,
+        NewApp,
+    )
+    return nil, nil // Wire generates the actual implementation
+}
+
+// Run: wire gen ./...
+```
+
+## Provider Sets
+
+```go
+// Group related providers
+var DatabaseSet = wire.NewSet(
+    NewDatabase,
+    NewUserRepository,
+    NewOrderRepository,
+)
+
+var ServiceSet = wire.NewSet(
+    NewUserService,
+    NewOrderService,
+    NewPaymentService,
+)
+
+var AppSet = wire.NewSet(
+    DatabaseSet,
+    ServiceSet,
+    NewApp,
+)
+
+// Use in injector
+func InitializeApp(cfg *Config) (*App, error) {
+    wire.Build(AppSet)
+    return nil, nil
+}
+```
+
+## Interface Bindings
+
+```go
+// Interface
+type UserRepository interface {
+    FindByID(id int) (*User, error)
+    Save(user *User) error
+}
+
+// Implementation
+type PostgresUserRepository struct {
+    db *Database
+}
+
+func NewPostgresUserRepository(db *Database) *PostgresUserRepository {
+    return &PostgresUserRepository{db: db}
+}
+
+// Bind implementation to interface
+var RepositorySet = wire.NewSet(
+    NewPostgresUserRepository,
+    wire.Bind(new(UserRepository), new(*PostgresUserRepository)),
+)
+
+// Service now depends on interface
+func NewUserService(repo UserRepository) *UserService {
+    return &UserService{repo: repo}
+}
+```
+
+## Cleanup Functions
+
+```go
+// Provider with cleanup
+func NewDatabase(cfg *Config) (*Database, func(), error) {
+    db, err := sql.Open("postgres", cfg.DSN)
+    if err != nil {
+        return nil, nil, err
+    }
+    
+    cleanup := func() {
+        db.Close()
+    }
+    
+    return &Database{db: db}, cleanup, nil
+}
+
+// Injector returns cleanup function
+func InitializeApp(cfg *Config) (*App, func(), error) {
+    wire.Build(AppSet)
+    return nil, nil, nil
+}
+
+// Usage
+func main() {
+    app, cleanup, err := InitializeApp(cfg)
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer cleanup() // Cleanup all resources
+    
+    app.Run()
+}
+```
+
+## Struct Providers
+
+```go
+// Provide struct fields
+type Config struct {
+    DB     DBConfig
+    Server ServerConfig
+}
+
+var ConfigSet = wire.NewSet(
+    wire.FieldsOf(new(*Config), "DB", "Server"),
+)
+
+// Or struct with all exported fields
+var ConfigSet = wire.NewSet(
+    wire.Struct(new(Config), "*"),
+)
+```
+
+## Values
+
+```go
+// Provide specific values
+func InitializeApp() (*App, error) {
+    wire.Build(
+        wire.Value(Config{Port: 8080}),
+        wire.InterfaceValue(new(io.Writer), os.Stdout),
+        NewApp,
+    )
+    return nil, nil
+}
+```
+
+## Generated Code (wire_gen.go)
+
+```go
+// Code generated by Wire. DO NOT EDIT.
+
+package main
+
+func InitializeApp(cfg *Config) (*App, func(), error) {
+    database, cleanup, err := NewDatabase(cfg)
+    if err != nil {
+        return nil, nil, err
+    }
+    userRepository := NewUserRepository(database)
+    userService := NewUserService(userRepository)
+    app := NewApp(userService)
+    return app, func() {
+        cleanup()
+    }, nil
+}
+```

package/rules/golang/zap-logging/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: Zap Logging
+description: Blazing fast structured logging from Uber.
+metadata:
+  labels: [golang, zap, logging, observability]
+  triggers:
+    files: ['**/logger.go', '**/main.go']
+    keywords: [zap, Logger, SugaredLogger, zapcore]
+---
+
+# Zap Logging Standards
+
+## Setup
+
+```go
+import "go.uber.org/zap"
+
+// Development (human readable)
+func NewDevelopmentLogger() *zap.Logger {
+    logger, _ := zap.NewDevelopment()
+    return logger
+}
+
+// Production (JSON, optimized)
+func NewProductionLogger() *zap.Logger {
+    logger, _ := zap.NewProduction()
+    return logger
+}
+
+// With options
+func NewLogger() *zap.Logger {
+    cfg := zap.NewProductionConfig()
+    cfg.Level = zap.NewAtomicLevelAt(zap.InfoLevel)
+    cfg.OutputPaths = []string{"stdout", "/var/log/app.log"}
+    cfg.EncoderConfig.TimeKey = "timestamp"
+    cfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
+
+    logger, _ := cfg.Build()
+    return logger
+}
+```
+
+## Logger vs SugaredLogger
+
+```go
+// Logger - faster, type-safe
+logger := zap.NewProduction()
+logger.Info("User logged in",
+    zap.String("user_id", "123"),
+    zap.Int("attempt", 1),
+    zap.Duration("latency", time.Millisecond*50),
+)
+
+// SugaredLogger - convenient, slower
+sugar := logger.Sugar()
+sugar.Infow("User logged in",
+    "user_id", "123",
+    "attempt", 1,
+    "latency", time.Millisecond*50,
+)
+sugar.Infof("User %s logged in", userID)
+```
+
+## Structured Fields
+
+```go
+logger.Info("Request completed",
+    zap.String("method", "GET"),
+    zap.String("path", "/users"),
+    zap.Int("status", 200),
+    zap.Duration("latency", latency),
+    zap.String("client_ip", clientIP),
+    zap.Any("headers", headers),     // Any type
+    zap.Error(err),                   // Error field
+    zap.Stack("stacktrace"),          // Stack trace
+)
+
+// Namespaced fields
+logger.Info("Request",
+    zap.Namespace("http"),
+    zap.String("method", "GET"),
+    zap.Int("status", 200),
+)
+// Output: {"http": {"method": "GET", "status": 200}}
+```
+
+## Log Levels
+
+```go
+logger.Debug("Debug message")   // -1
+logger.Info("Info message")     // 0
+logger.Warn("Warning message")  // 1
+logger.Error("Error message")   // 2
+logger.DPanic("DPanic message") // 3 (panics in development)
+logger.Panic("Panic message")   // 4 (always panics)
+logger.Fatal("Fatal message")   // 5 (calls os.Exit(1))
+
+// Check level before expensive operations
+if logger.Core().Enabled(zap.DebugLevel) {
+    logger.Debug("Expensive", zap.Any("data", computeExpensiveData()))
+}
+```
+
+## Child Loggers
+
+```go
+// Add fields to all subsequent logs
+requestLogger := logger.With(
+    zap.String("request_id", requestID),
+    zap.String("user_id", userID),
+)
+
+requestLogger.Info("Processing request")
+requestLogger.Info("Request completed")
+// Both logs include request_id and user_id
+
+// Named logger
+dbLogger := logger.Named("database")
+dbLogger.Info("Query executed")
+// Output: {"logger": "database", "msg": "Query executed"}
+```
+
+## Gin Integration
+
+```go
+import (
+    "github.com/gin-gonic/gin"
+    "go.uber.org/zap"
+)
+
+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("method", c.Request.Method),
+            zap.String("path", path),
+            zap.Int("status", c.Writer.Status()),
+            zap.Duration("latency", time.Since(start)),
+            zap.String("client_ip", c.ClientIP()),
+        )
+    }
+}
+
+r := gin.New()
+r.Use(GinLogger(logger))
+```
+
+## Custom Encoder
+
+```go
+cfg := zap.NewProductionConfig()
+cfg.EncoderConfig = zapcore.EncoderConfig{
+    TimeKey:        "ts",
+    LevelKey:       "level",
+    NameKey:        "logger",
+    CallerKey:      "caller",
+    MessageKey:     "msg",
+    StacktraceKey:  "stacktrace",
+    LineEnding:     zapcore.DefaultLineEnding,
+    EncodeLevel:    zapcore.LowercaseLevelEncoder,
+    EncodeTime:     zapcore.ISO8601TimeEncoder,
+    EncodeDuration: zapcore.MillisDurationEncoder,
+    EncodeCaller:   zapcore.ShortCallerEncoder,
+}
+```
+
+## Sampling
+
+```go
+// Sample logs to reduce volume in production
+cfg := zap.NewProductionConfig()
+cfg.Sampling = &zap.SamplingConfig{
+    Initial:    100,  // First 100 per second logged
+    Thereafter: 100,  // Then every 100th message
+}
+```
+
+## Global Logger
+
+```go
+// Replace global logger
+logger := zap.NewProduction()
+zap.ReplaceGlobals(logger)
+
+// Use global
+zap.L().Info("Using global logger")
+zap.S().Infow("Using global sugar")
+
+// Always sync before exit
+defer logger.Sync()
+```
+
+## Best Practices
+
+1. **Production**: Use `zap.NewProduction()` for JSON output
+2. **Sync**: Always call `logger.Sync()` before exit
+3. **Fields**: Prefer `zap.String()` etc. over SugaredLogger
+4. **Child loggers**: Add request context with `With()`
+5. **Sampling**: Enable in high-throughput production

package/rules/golang/zap-logging/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Zap Logging References
+
+## References
+
+- [**Logger Configuration**](logger-config.md) - Setup, levels, output formats
+
+## Quick Checks
+
+- [ ] Use sugared logger for development convenience
+- [ ] Use standard logger for production performance
+- [ ] Structured logging with typed fields
+- [ ] Configure appropriate log levels
+- [ ] Use sampling for high-volume logs