devflow-kit 1.0.0 → 1.2.0

package/shared/skills/go/references/patterns.md

@@ -0,0 +1,232 @@
+# Go Correct Patterns
+
+Extended correct patterns for Go development. Reference from main SKILL.md.
+
+## Table-Driven Tests
+
+```go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 2, 3, 5},
+        {"negative numbers", -1, -2, -3},
+        {"zero", 0, 0, 0},
+        {"mixed signs", -1, 3, 2},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            if result != tt.expected {
+                t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+---
+
+## Functional Options
+
+```go
+type Server struct {
+    addr    string
+    timeout time.Duration
+    logger  *slog.Logger
+}
+
+type Option func(*Server)
+
+func WithAddr(addr string) Option {
+    return func(s *Server) { s.addr = addr }
+}
+
+func WithTimeout(d time.Duration) Option {
+    return func(s *Server) { s.timeout = d }
+}
+
+func WithLogger(l *slog.Logger) Option {
+    return func(s *Server) { s.logger = l }
+}
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{
+        addr:    ":8080",           // sensible default
+        timeout: 30 * time.Second,  // sensible default
+        logger:  slog.Default(),
+    }
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+
+// Usage
+srv := NewServer(
+    WithAddr(":9090"),
+    WithTimeout(60 * time.Second),
+)
+```
+
+---
+
+## Custom Error Types
+
+```go
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
+}
+
+type NotFoundError struct {
+    Resource string
+    ID       string
+}
+
+func (e *NotFoundError) Error() string {
+    return fmt.Sprintf("%s %s not found", e.Resource, e.ID)
+}
+
+// Usage with errors.As
+func handleErr(err error) {
+    var validErr *ValidationError
+    if errors.As(err, &validErr) {
+        log.Printf("bad input: field=%s msg=%s", validErr.Field, validErr.Message)
+        return
+    }
+    var notFound *NotFoundError
+    if errors.As(err, &notFound) {
+        log.Printf("missing: %s/%s", notFound.Resource, notFound.ID)
+        return
+    }
+    log.Printf("unexpected: %v", err)
+}
+```
+
+---
+
+## Middleware Pattern
+
+```go
+type Middleware func(http.Handler) http.Handler
+
+func Logging(logger *slog.Logger) Middleware {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            start := time.Now()
+            next.ServeHTTP(w, r)
+            logger.Info("request",
+                "method", r.Method,
+                "path", r.URL.Path,
+                "duration", time.Since(start),
+            )
+        })
+    }
+}
+
+func Recovery() Middleware {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            defer func() {
+                if err := recover(); err != nil {
+                    w.WriteHeader(http.StatusInternalServerError)
+                    slog.Error("panic recovered", "error", err)
+                }
+            }()
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+
+// Chain composes middleware in order
+func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
+    for i := len(middlewares) - 1; i >= 0; i-- {
+        handler = middlewares[i](handler)
+    }
+    return handler
+}
+
+// Usage
+mux := http.NewServeMux()
+mux.HandleFunc("/api/users", handleUsers)
+handler := Chain(mux, Recovery(), Logging(logger))
+```
+
+---
+
+## Graceful Shutdown
+
+```go
+func main() {
+    srv := &http.Server{Addr: ":8080", Handler: mux}
+
+    go func() {
+        if err := srv.ListenAndServe(); err != http.ErrServerClosed {
+            slog.Error("server error", "error", err)
+        }
+    }()
+
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+
+    if err := srv.Shutdown(ctx); err != nil {
+        slog.Error("shutdown error", "error", err)
+    }
+    slog.Info("server stopped")
+}
+```
+
+---
+
+## Constructor Pattern
+
+```go
+// Validate at construction - enforce invariants
+func NewUser(name, email string) (*User, error) {
+    if name == "" {
+        return nil, &ValidationError{Field: "name", Message: "required"}
+    }
+    if !strings.Contains(email, "@") {
+        return nil, &ValidationError{Field: "email", Message: "invalid format"}
+    }
+    return &User{
+        ID:        uuid.New().String(),
+        Name:      name,
+        Email:     email,
+        CreatedAt: time.Now(),
+    }, nil
+}
+```
+
+---
+
+## Structured Logging with slog
+
+```go
+func ProcessOrder(ctx context.Context, orderID string) error {
+    logger := slog.With("order_id", orderID, "trace_id", traceID(ctx))
+
+    logger.Info("processing order")
+
+    items, err := fetchItems(ctx, orderID)
+    if err != nil {
+        logger.Error("failed to fetch items", "error", err)
+        return fmt.Errorf("fetching items for order %s: %w", orderID, err)
+    }
+
+    logger.Info("items fetched", "count", len(items))
+    return nil
+}
+```

package/shared/skills/go/references/violations.md

@@ -0,0 +1,205 @@
+# Go Violation Examples
+
+Extended violation patterns for Go reviews. Reference from main SKILL.md.
+
+## Error Handling Violations
+
+### Ignored Errors
+
+```go
+// VIOLATION: Silently discarding error
+data, _ := json.Marshal(user)
+w.Write(data)
+
+// VIOLATION: Error ignored in deferred call
+defer file.Close() // Close() returns error
+
+// VIOLATION: Swallowing error with log
+if err != nil {
+    log.Println("something failed") // Error details lost
+    return nil
+}
+```
+
+### Unwrapped Errors
+
+```go
+// VIOLATION: No context on error
+func LoadConfig(path string) (*Config, error) {
+    data, err := os.ReadFile(path)
+    if err != nil {
+        return nil, err // Caller has no idea what failed
+    }
+    var cfg Config
+    if err := json.Unmarshal(data, &cfg); err != nil {
+        return nil, err // Which unmarshal? What file?
+    }
+    return &cfg, nil
+}
+```
+
+---
+
+## Goroutine Leak Violations
+
+### Fire-and-Forget Goroutine
+
+```go
+// VIOLATION: No way to stop or wait for this goroutine
+func StartPoller() {
+    go func() {
+        for {
+            poll()
+            time.Sleep(10 * time.Second)
+        }
+    }()
+}
+
+// VIOLATION: Goroutine blocks forever on channel nobody reads
+func process(items []Item) {
+    ch := make(chan Result)
+    for _, item := range items {
+        go func(i Item) {
+            ch <- compute(i) // Blocks if nobody reads
+        }(item)
+    }
+    // Only reads first result - rest leak
+    result := <-ch
+    _ = result
+}
+```
+
+### Missing Context Cancellation
+
+```go
+// VIOLATION: Goroutine ignores context
+func Fetch(ctx context.Context, url string) ([]byte, error) {
+    ch := make(chan []byte, 1)
+    go func() {
+        resp, _ := http.Get(url) // Ignores ctx cancellation
+        body, _ := io.ReadAll(resp.Body)
+        ch <- body
+    }()
+    return <-ch, nil
+}
+```
+
+---
+
+## Interface Pollution Violations
+
+### Premature Interface Definition
+
+```go
+// VIOLATION: Interface defined at producer, not consumer
+package user
+
+type UserStore interface { // Only one implementation exists
+    Get(id string) (*User, error)
+    Save(u *User) error
+    Delete(id string) error
+    List() ([]*User, error)
+    Count() (int, error)
+}
+
+type PostgresStore struct{ db *sql.DB }
+
+func (s *PostgresStore) Get(id string) (*User, error) { ... }
+// ... implements all 5 methods
+```
+
+### God Interface
+
+```go
+// VIOLATION: Interface too large - impossible to mock cleanly
+type Service interface {
+    CreateUser(ctx context.Context, u *User) error
+    GetUser(ctx context.Context, id string) (*User, error)
+    UpdateUser(ctx context.Context, u *User) error
+    DeleteUser(ctx context.Context, id string) error
+    ListUsers(ctx context.Context) ([]*User, error)
+    SendEmail(ctx context.Context, to string, body string) error
+    GenerateReport(ctx context.Context) ([]byte, error)
+    ProcessPayment(ctx context.Context, amt int) error
+}
+```
+
+---
+
+## Naked Return Violations
+
+```go
+// VIOLATION: Naked returns obscure what's being returned
+func divide(a, b float64) (result float64, err error) {
+    if b == 0 {
+        err = errors.New("division by zero")
+        return // What is result here? Zero - but not obvious
+    }
+    result = a / b
+    return // Have to trace back to find return values
+}
+```
+
+---
+
+## init() Abuse Violations
+
+```go
+// VIOLATION: Side effects in init - runs on import
+func init() {
+    db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
+    if err != nil {
+        log.Fatal(err) // Crashes on import
+    }
+    globalDB = db
+}
+
+// VIOLATION: Registration magic in init
+func init() {
+    http.HandleFunc("/health", healthCheck) // Hidden route registration
+    prometheus.MustRegister(requestCounter) // Panics if called twice
+}
+```
+
+---
+
+## Mutex Violations
+
+```go
+// VIOLATION: Copying mutex (passes by value)
+type Cache struct {
+    mu   sync.Mutex
+    data map[string]string
+}
+
+func process(c Cache) { // c is a COPY - mutex is copied too
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.data["key"] = "val"
+}
+
+// VIOLATION: Forgetting to unlock
+func (c *Cache) Get(key string) string {
+    c.mu.Lock()
+    if val, ok := c.data[key]; ok {
+        return val // Mutex never unlocked!
+    }
+    c.mu.Unlock()
+    return ""
+}
+```
+
+---
+
+## Slice and Map Violations
+
+```go
+// VIOLATION: Nil map write (runtime panic)
+var m map[string]int
+m["key"] = 1 // panic: assignment to entry in nil map
+
+// VIOLATION: Sharing slice backing array
+func getFirstThree(s []int) []int {
+    return s[:3] // Shares backing array - mutations leak
+}
+```

package/shared/skills/java/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: java
+description: This skill should be used when the user works with Java files (.java), asks about "records", "sealed classes", "Optional", "streams", "composition over inheritance", or discusses modern Java patterns and API design. Provides patterns for type system usage, error handling, immutability, and concurrency.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.java"
+  exclude:
+    - "**/build/**"
+    - "**/target/**"
+---
+
+# Java Patterns
+
+Reference for modern Java patterns, type system, and best practices.
+
+## Iron Law
+
+> **FAVOR COMPOSITION OVER INHERITANCE**
+>
+> Delegation and interfaces over class hierarchies. Inheritance creates tight coupling,
+> breaks encapsulation, and makes refactoring dangerous. Use interfaces for polymorphism,
+> records for data, and sealed classes for restricted hierarchies. Extend only when the
+> "is-a" relationship is genuinely invariant.
+
+## When This Skill Activates
+
+- Working with Java codebases
+- Designing APIs with modern Java features
+- Using records, sealed classes, Optional
+- Implementing concurrent code
+- Structuring Java packages
+
+---
+
+## Type System (Modern Java)
+
+### Records for Data
+
+```java
+// BAD: Mutable POJO with getters/setters
+// GOOD: Immutable record
+public record User(String name, String email, Instant createdAt) {
+    public User {
+        Objects.requireNonNull(name, "name must not be null");
+        Objects.requireNonNull(email, "email must not be null");
+    }
+}
+```
+
+### Sealed Classes for Restricted Hierarchies
+
+```java
+public sealed interface Result<T> permits Success, Failure {
+    record Success<T>(T value) implements Result<T> {}
+    record Failure<T>(String error) implements Result<T> {}
+}
+
+// Exhaustive pattern matching (Java 21+)
+switch (result) {
+    case Success<User> s -> handleSuccess(s.value());
+    case Failure<User> f -> handleError(f.error());
+}
+```
+
+### Optional for Absent Values
+
+```java
+// BAD: return null;
+// GOOD:
+public Optional<User> findById(String id) {
+    return Optional.ofNullable(userMap.get(id));
+}
+
+// BAD: if (optional.isPresent()) optional.get()
+// GOOD:
+optional.map(User::name).orElse("Anonymous");
+```
+
+---
+
+## Error Handling
+
+### Custom Exceptions with Context
+
+```java
+public class EntityNotFoundException extends RuntimeException {
+    private final String entityType;
+    private final String entityId;
+
+    public EntityNotFoundException(String entityType, String entityId) {
+        super("%s with id %s not found".formatted(entityType, entityId));
+        this.entityType = entityType;
+        this.entityId = entityId;
+    }
+}
+```
+
+### Try-with-Resources
+
+```java
+// Always use try-with-resources for AutoCloseable
+try (var conn = dataSource.getConnection();
+     var stmt = conn.prepareStatement(sql)) {
+    stmt.setString(1, id);
+    return mapResult(stmt.executeQuery());
+}
+```
+
+---
+
+## Immutability
+
+```java
+// Prefer unmodifiable collections
+List<String> names = List.of("Alice", "Bob");
+Map<String, Integer> scores = Map.of("Alice", 100, "Bob", 95);
+
+// Defensive copies in constructors
+public final class Team {
+    private final List<String> members;
+    public Team(List<String> members) {
+        this.members = List.copyOf(members);
+    }
+    public List<String> members() { return members; }
+}
+```
+
+---
+
+## Composition Over Inheritance
+
+```java
+// BAD: class UserService extends BaseService extends AbstractDAO
+// GOOD: compose via constructor injection
+public class UserService {
+    private final UserRepository repository;
+    private final EventPublisher events;
+
+    public UserService(UserRepository repository, EventPublisher events) {
+        this.repository = repository;
+        this.events = events;
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Returning null | `return null` | `return Optional.empty()` |
+| Checked exception abuse | `throws Exception` | Specific exceptions or unchecked |
+| Raw types | `List list` | `List<User> list` |
+| Deep inheritance | 4+ level hierarchy | Interfaces + composition |
+| Mutable data objects | `setName()/getName()` | Records or immutable classes |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Common Java violations
+- `references/patterns.md` - Extended Java patterns
+- `references/detection.md` - Detection patterns for Java issues
+- `references/modern-java.md` - Modern Java features (17-21+)
+
+---
+
+## Checklist
+
+- [ ] Records for pure data types
+- [ ] Sealed interfaces for type hierarchies
+- [ ] Optional instead of null returns
+- [ ] Composition over inheritance
+- [ ] Try-with-resources for all AutoCloseable
+- [ ] Immutable collections (List.of, Map.of)
+- [ ] No raw generic types
+- [ ] Custom exceptions with context
+- [ ] Streams for collection transforms
+- [ ] Constructor injection for dependencies