@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/golang/testify/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: Testify
+description: Testing toolkit with assertions, mocks, and suites.
+metadata:
+  labels: [golang, testify, testing, mock]
+  triggers:
+    files: ['**/*_test.go']
+    keywords: [testify, assert, require, mock, suite]
+---
+
+# Testify Standards
+
+## Assert Package
+
+```go
+import (
+    "testing"
+    "github.com/stretchr/testify/assert"
+)
+
+func TestSomething(t *testing.T) {
+    // Equality
+    assert.Equal(t, 123, result)
+    assert.NotEqual(t, 456, result)
+
+    // Boolean
+    assert.True(t, ok)
+    assert.False(t, failed)
+
+    // Nil checks
+    assert.Nil(t, err)
+    assert.NotNil(t, obj)
+
+    // Error checks
+    assert.NoError(t, err)
+    assert.Error(t, err)
+    assert.ErrorIs(t, err, ErrNotFound)
+    assert.ErrorContains(t, err, "not found")
+
+    // Collections
+    assert.Contains(t, slice, item)
+    assert.Len(t, slice, 3)
+    assert.Empty(t, slice)
+    assert.NotEmpty(t, slice)
+    assert.ElementsMatch(t, expected, actual)  // Order independent
+
+    // Comparison
+    assert.Greater(t, 2, 1)
+    assert.GreaterOrEqual(t, 2, 2)
+    assert.Less(t, 1, 2)
+
+    // Type assertions
+    assert.IsType(t, &User{}, obj)
+    assert.Implements(t, (*io.Reader)(nil), obj)
+
+    // With message
+    assert.Equal(t, expected, actual, "values should match")
+}
+```
+
+## Require Package
+
+```go
+import "github.com/stretchr/testify/require"
+
+func TestWithRequire(t *testing.T) {
+    // Stops test immediately on failure
+    user, err := GetUser(1)
+    require.NoError(t, err)       // Fails here stops test
+    require.NotNil(t, user)
+
+    // Continue knowing user is valid
+    assert.Equal(t, "John", user.Name)
+}
+```
+
+## Mock Package
+
+```go
+import (
+    "testing"
+    "github.com/stretchr/testify/mock"
+)
+
+// Interface to mock
+type UserRepository interface {
+    FindByID(id int) (*User, error)
+    Save(user *User) error
+}
+
+// Mock implementation
+type MockUserRepository struct {
+    mock.Mock
+}
+
+func (m *MockUserRepository) FindByID(id int) (*User, error) {
+    args := m.Called(id)
+    if args.Get(0) == nil {
+        return nil, args.Error(1)
+    }
+    return args.Get(0).(*User), args.Error(1)
+}
+
+func (m *MockUserRepository) Save(user *User) error {
+    args := m.Called(user)
+    return args.Error(0)
+}
+
+// Test using mock
+func TestUserService(t *testing.T) {
+    mockRepo := new(MockUserRepository)
+
+    // Setup expectations
+    mockRepo.On("FindByID", 1).Return(&User{ID: 1, Name: "John"}, nil)
+    mockRepo.On("Save", mock.Anything).Return(nil)
+
+    service := NewUserService(mockRepo)
+    user, err := service.GetUser(1)
+
+    assert.NoError(t, err)
+    assert.Equal(t, "John", user.Name)
+
+    // Verify expectations
+    mockRepo.AssertExpectations(t)
+    mockRepo.AssertCalled(t, "FindByID", 1)
+    mockRepo.AssertNumberOfCalls(t, "FindByID", 1)
+}
+```
+
+## Mock Matching
+
+```go
+// Exact match
+mockRepo.On("FindByID", 1).Return(user, nil)
+
+// Any value
+mockRepo.On("Save", mock.Anything).Return(nil)
+
+// Type match
+mockRepo.On("Save", mock.AnythingOfType("*User")).Return(nil)
+
+// Custom matcher
+mockRepo.On("FindByID", mock.MatchedBy(func(id int) bool {
+    return id > 0
+})).Return(user, nil)
+
+// Multiple calls
+mockRepo.On("FindByID", 1).Return(user, nil).Once()
+mockRepo.On("FindByID", 1).Return(nil, ErrNotFound).Once()
+
+// Call order
+mockRepo.On("Save", mock.Anything).Return(nil).Run(func(args mock.Arguments) {
+    user := args.Get(0).(*User)
+    user.ID = 123  // Modify argument
+})
+```
+
+## Suite Package
+
+```go
+import (
+    "testing"
+    "github.com/stretchr/testify/suite"
+)
+
+type UserServiceTestSuite struct {
+    suite.Suite
+    db      *sql.DB
+    service *UserService
+}
+
+func (s *UserServiceTestSuite) SetupSuite() {
+    // Run once before all tests
+    s.db = setupTestDB()
+}
+
+func (s *UserServiceTestSuite) TearDownSuite() {
+    // Run once after all tests
+    s.db.Close()
+}
+
+func (s *UserServiceTestSuite) SetupTest() {
+    // Run before each test
+    s.service = NewUserService(s.db)
+}
+
+func (s *UserServiceTestSuite) TearDownTest() {
+    // Run after each test
+    cleanupTestData(s.db)
+}
+
+func (s *UserServiceTestSuite) TestGetUser() {
+    user, err := s.service.GetUser(1)
+    s.NoError(err)
+    s.Equal("John", user.Name)
+}
+
+func (s *UserServiceTestSuite) TestCreateUser() {
+    user, err := s.service.CreateUser("Jane", "jane@example.com")
+    s.NoError(err)
+    s.NotZero(user.ID)
+}
+
+// Run the suite
+func TestUserServiceSuite(t *testing.T) {
+    suite.Run(t, new(UserServiceTestSuite))
+}
+```
+
+## Table-Driven Tests
+
+```go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive", 1, 2, 3},
+        {"negative", -1, -1, -2},
+        {"zero", 0, 0, 0},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            assert.Equal(t, tt.expected, result)
+        })
+    }
+}
+```
+
+## Best Practices
+
+1. **require vs assert**: Use `require` for setup, `assert` for verification
+2. **Mocks**: Generate with mockery for large interfaces
+3. **Suites**: Use for tests sharing setup/teardown
+4. **Messages**: Add context with assertion messages
+5. **Parallel**: Use `t.Parallel()` for independent tests

package/rules/golang/testify/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Testify Testing References
+
+## References
+
+- [**Assert Patterns**](assert-patterns.md) - Assertions, require, suite
+
+## Quick Checks
+
+- [ ] Use assert for non-fatal assertions
+- [ ] Use require for fatal assertions
+- [ ] Test suites for setup/teardown
+- [ ] Mock package for interfaces
+- [ ] Table-driven tests with subtests

package/rules/golang/testify/references/assert-patterns.md

@@ -0,0 +1,170 @@
+# Testify Assert Patterns
+
+## Assertions
+
+```go
+import (
+    "testing"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+func TestUserService(t *testing.T) {
+    // Basic assertions (non-fatal, continues on failure)
+    assert.Equal(t, expected, actual)
+    assert.NotEqual(t, expected, actual)
+    assert.True(t, condition)
+    assert.False(t, condition)
+    assert.Nil(t, value)
+    assert.NotNil(t, value)
+    assert.Empty(t, slice)
+    assert.NotEmpty(t, slice)
+    assert.Len(t, slice, 5)
+    assert.Contains(t, slice, element)
+    assert.ElementsMatch(t, expected, actual)
+
+    // Require (fatal, stops on failure)
+    require.NoError(t, err)
+    require.NotNil(t, user)
+    
+    // Error assertions
+    assert.Error(t, err)
+    assert.NoError(t, err)
+    assert.ErrorIs(t, err, ErrNotFound)
+    assert.ErrorContains(t, err, "not found")
+
+    // Type assertions
+    assert.IsType(t, &User{}, obj)
+    assert.Implements(t, (*io.Reader)(nil), obj)
+
+    // Numeric comparisons
+    assert.Greater(t, 5, 3)
+    assert.GreaterOrEqual(t, 5, 5)
+    assert.Less(t, 3, 5)
+    assert.InDelta(t, 3.14, result, 0.01)
+
+    // String assertions
+    assert.Regexp(t, `^[a-z]+$`, str)
+    assert.JSONEq(t, `{"name":"John"}`, jsonStr)
+}
+```
+
+## Table-Driven Tests
+
+```go
+func TestCalculator_Add(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 2, 3, 5},
+        {"negative numbers", -2, -3, -5},
+        {"mixed numbers", -2, 3, 1},
+        {"zeros", 0, 0, 0},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            assert.Equal(t, tt.expected, result)
+        })
+    }
+}
+```
+
+## Test Suites
+
+```go
+import (
+    "testing"
+    "github.com/stretchr/testify/suite"
+)
+
+type UserServiceTestSuite struct {
+    suite.Suite
+    db      *Database
+    service *UserService
+}
+
+// Run before each test
+func (s *UserServiceTestSuite) SetupTest() {
+    s.db = NewTestDatabase()
+    s.service = NewUserService(s.db)
+}
+
+// Run after each test
+func (s *UserServiceTestSuite) TearDownTest() {
+    s.db.Close()
+}
+
+// Run once before all tests
+func (s *UserServiceTestSuite) SetupSuite() {
+    // Initialize shared resources
+}
+
+func (s *UserServiceTestSuite) TestCreateUser() {
+    user, err := s.service.Create("John", "john@example.com")
+    
+    s.NoError(err)
+    s.NotNil(user)
+    s.Equal("John", user.Name)
+}
+
+func (s *UserServiceTestSuite) TestFindUser() {
+    // Setup
+    s.db.Insert(&User{ID: 1, Name: "John"})
+    
+    // Test
+    user, err := s.service.FindByID(1)
+    
+    // Assert
+    s.Require().NoError(err)
+    s.Equal("John", user.Name)
+}
+
+// Run the suite
+func TestUserServiceTestSuite(t *testing.T) {
+    suite.Run(t, new(UserServiceTestSuite))
+}
+```
+
+## Mocking
+
+```go
+import "github.com/stretchr/testify/mock"
+
+type MockUserRepository struct {
+    mock.Mock
+}
+
+func (m *MockUserRepository) FindByID(id int) (*User, error) {
+    args := m.Called(id)
+    if args.Get(0) == nil {
+        return nil, args.Error(1)
+    }
+    return args.Get(0).(*User), args.Error(1)
+}
+
+func (m *MockUserRepository) Save(user *User) error {
+    args := m.Called(user)
+    return args.Error(0)
+}
+
+func TestUserService_GetUser(t *testing.T) {
+    // Setup mock
+    mockRepo := new(MockUserRepository)
+    mockRepo.On("FindByID", 1).Return(&User{ID: 1, Name: "John"}, nil)
+    
+    service := NewUserService(mockRepo)
+    
+    // Test
+    user, err := service.GetUser(1)
+    
+    // Assert
+    assert.NoError(t, err)
+    assert.Equal(t, "John", user.Name)
+    mockRepo.AssertExpectations(t)
+    mockRepo.AssertCalled(t, "FindByID", 1)
+}
+```

package/rules/golang/validator/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: Validator
+description: Struct validation using tags for Go.
+metadata:
+  labels: [golang, validator, validation]
+  triggers:
+    files: ['**/*.go']
+    keywords: [validator, validate, binding, Validate]
+---
+
+# Validator Standards
+
+## Basic Usage
+
+```go
+import (
+    "github.com/go-playground/validator/v10"
+)
+
+var validate = validator.New()
+
+type User struct {
+    Name     string `validate:"required,min=2,max=100"`
+    Email    string `validate:"required,email"`
+    Age      int    `validate:"gte=0,lte=120"`
+    Password string `validate:"required,min=8"`
+}
+
+func ValidateUser(user User) error {
+    return validate.Struct(user)
+}
+
+// Error handling
+err := validate.Struct(user)
+if err != nil {
+    for _, err := range err.(validator.ValidationErrors) {
+        fmt.Printf("Field: %s, Tag: %s, Value: %v\n",
+            err.Field(), err.Tag(), err.Value())
+    }
+}
+```
+
+## Common Validations
+
+```go
+type Request struct {
+    // Required
+    Name string `validate:"required"`
+
+    // String length
+    Title string `validate:"min=1,max=100"`
+
+    // Numbers
+    Age   int     `validate:"gte=0,lte=150"`
+    Price float64 `validate:"gt=0"`
+
+    // Email, URL
+    Email   string `validate:"email"`
+    Website string `validate:"url"`
+
+    // UUID
+    ID string `validate:"uuid4"`
+
+    // Enum
+    Status string `validate:"oneof=pending active completed"`
+
+    // Contains
+    Code string `validate:"contains=PREFIX"`
+
+    // Regex (alpha, alphanum, numeric, etc.)
+    Username string `validate:"alphanum,min=3,max=20"`
+
+    // Date/Time
+    StartDate string `validate:"datetime=2006-01-02"`
+}
+```
+
+## Nested Structs
+
+```go
+type Address struct {
+    Street  string `validate:"required"`
+    City    string `validate:"required"`
+    ZipCode string `validate:"required,len=5"`
+}
+
+type User struct {
+    Name    string  `validate:"required"`
+    Address Address `validate:"required"`  // Validates nested
+}
+
+type Company struct {
+    Employees []User `validate:"required,min=1,dive"` // Validates each element
+}
+
+type Config struct {
+    Settings map[string]string `validate:"required,dive,keys,required,endkeys,required"`
+}
+```
+
+## Cross-Field Validation
+
+```go
+type DateRange struct {
+    StartDate time.Time `validate:"required"`
+    EndDate   time.Time `validate:"required,gtfield=StartDate"`
+}
+
+type PasswordChange struct {
+    Password        string `validate:"required,min=8"`
+    ConfirmPassword string `validate:"required,eqfield=Password"`
+}
+
+type Transfer struct {
+    FromAccount string `validate:"required"`
+    ToAccount   string `validate:"required,nefield=FromAccount"`
+}
+```
+
+## Custom Validators
+
+```go
+func init() {
+    validate.RegisterValidation("nowhitespace", noWhitespaceValidator)
+    validate.RegisterValidation("strongpassword", strongPasswordValidator)
+}
+
+func noWhitespaceValidator(fl validator.FieldLevel) bool {
+    return !strings.Contains(fl.Field().String(), " ")
+}
+
+func strongPasswordValidator(fl validator.FieldLevel) bool {
+    password := fl.Field().String()
+    hasUpper := regexp.MustCompile(`[A-Z]`).MatchString(password)
+    hasLower := regexp.MustCompile(`[a-z]`).MatchString(password)
+    hasNumber := regexp.MustCompile(`[0-9]`).MatchString(password)
+    hasSpecial := regexp.MustCompile(`[!@#$%^&*]`).MatchString(password)
+    return hasUpper && hasLower && hasNumber && hasSpecial
+}
+
+type User struct {
+    Username string `validate:"required,nowhitespace"`
+    Password string `validate:"required,min=8,strongpassword"`
+}
+```
+
+## Conditional Validation
+
+```go
+type User struct {
+    Type  string `validate:"required,oneof=personal business"`
+    TaxID string `validate:"required_if=Type business"`
+}
+
+type Order struct {
+    PaymentMethod string `validate:"required,oneof=card cash"`
+    CardNumber    string `validate:"required_if=PaymentMethod card"`
+}
+
+// Other conditional tags:
+// required_unless, required_with, required_without
+// required_with_all, required_without_all
+```
+
+## Gin Integration
+
+```go
+import (
+    "github.com/gin-gonic/gin"
+    "github.com/gin-gonic/gin/binding"
+    "github.com/go-playground/validator/v10"
+)
+
+func init() {
+    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
+        v.RegisterValidation("customtag", customValidator)
+    }
+}
+
+type CreateUserRequest struct {
+    Name  string `json:"name" binding:"required,min=2"`
+    Email string `json:"email" binding:"required,email"`
+}
+
+func CreateUser(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(400, gin.H{"error": err.Error()})
+        return
+    }
+    // req is validated
+}
+```
+
+## Error Translation
+
+```go
+import (
+    "github.com/go-playground/locales/en"
+    ut "github.com/go-playground/universal-translator"
+    en_translations "github.com/go-playground/validator/v10/translations/en"
+)
+
+var (
+    uni      *ut.UniversalTranslator
+    trans    ut.Translator
+    validate *validator.Validate
+)
+
+func init() {
+    en := en.New()
+    uni = ut.New(en, en)
+    trans, _ = uni.GetTranslator("en")
+
+    validate = validator.New()
+    en_translations.RegisterDefaultTranslations(validate, trans)
+}
+
+func translateError(err error) []string {
+    var messages []string
+    for _, e := range err.(validator.ValidationErrors) {
+        messages = append(messages, e.Translate(trans))
+    }
+    return messages
+}
+```
+
+## Best Practices
+
+1. **Singleton**: Create one validator instance
+2. **Custom validators**: Register at init time
+3. **Dive**: Use for slices and maps
+4. **Translations**: Provide user-friendly messages
+5. **Gin**: Use binding tags for automatic validation

package/rules/golang/validator/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Validator References
+
+## References
+
+- [**Validation Tags**](validation-tags.md) - Built-in validators, custom rules
+
+## Quick Checks
+
+- [ ] Use struct tags for validation rules
+- [ ] Register custom validators as needed
+- [ ] Handle validation errors gracefully
+- [ ] Use dive for slice/map validation
+- [ ] Conditional validation with required_if