devflow-kit 1.1.0 → 1.2.0

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

@@ -0,0 +1,312 @@
+# Go Concurrency Patterns
+
+Advanced concurrency patterns for Go. Reference from main SKILL.md.
+
+## errgroup for Structured Concurrency
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func FetchAll(ctx context.Context, urls []string) ([]Response, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    responses := make([]Response, len(urls))
+
+    for i, url := range urls {
+        g.Go(func() error {
+            resp, err := fetch(ctx, url)
+            if err != nil {
+                return fmt.Errorf("fetching %s: %w", url, err)
+            }
+            responses[i] = resp // Safe: each goroutine writes to unique index
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return responses, nil
+}
+```
+
+### errgroup with Concurrency Limit
+
+```go
+func ProcessItems(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(10) // Maximum 10 concurrent goroutines
+
+    for _, item := range items {
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+```
+
+---
+
+## Worker Pool
+
+```go
+func WorkerPool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
+    results := make(chan Result, workers)
+
+    var wg sync.WaitGroup
+    for range workers {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for {
+                select {
+                case job, ok := <-jobs:
+                    if !ok {
+                        return
+                    }
+                    results <- process(ctx, job)
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    return results
+}
+
+// Usage
+jobs := make(chan Job, 100)
+results := WorkerPool(ctx, jobs, 5)
+
+// Send jobs
+go func() {
+    defer close(jobs)
+    for _, j := range allJobs {
+        jobs <- j
+    }
+}()
+
+// Collect results
+for r := range results {
+    fmt.Println(r)
+}
+```
+
+---
+
+## Fan-Out / Fan-In
+
+```go
+// Fan-out: one source, multiple workers
+func fanOut(ctx context.Context, input <-chan int, workers int) []<-chan int {
+    channels := make([]<-chan int, workers)
+    for i := range workers {
+        channels[i] = worker(ctx, input)
+    }
+    return channels
+}
+
+func worker(ctx context.Context, input <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for n := range input {
+            select {
+            case out <- n * n:
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+
+// Fan-in: multiple sources, one destination
+func fanIn(ctx context.Context, channels ...<-chan int) <-chan int {
+    merged := make(chan int)
+    var wg sync.WaitGroup
+
+    for _, ch := range channels {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for val := range ch {
+                select {
+                case merged <- val:
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(merged)
+    }()
+
+    return merged
+}
+```
+
+---
+
+## Select with Timeout
+
+```go
+func fetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+
+    ch := make(chan result, 1)
+    go func() {
+        data, err := doFetch(ctx, url)
+        ch <- result{data, err}
+    }()
+
+    select {
+    case r := <-ch:
+        return r.data, r.err
+    case <-ctx.Done():
+        return nil, fmt.Errorf("fetch %s: %w", url, ctx.Err())
+    }
+}
+
+type result struct {
+    data []byte
+    err  error
+}
+```
+
+### Select for Multiple Sources
+
+```go
+func merge(ctx context.Context, primary, fallback <-chan Event) <-chan Event {
+    out := make(chan Event)
+    go func() {
+        defer close(out)
+        for {
+            select {
+            case e, ok := <-primary:
+                if !ok {
+                    return
+                }
+                out <- e
+            case e, ok := <-fallback:
+                if !ok {
+                    return
+                }
+                out <- e
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+```
+
+---
+
+## Mutex vs Channels
+
+### Use Mutex When
+
+```go
+// Protecting shared state with simple read/write
+type SafeCounter struct {
+    mu sync.RWMutex
+    v  map[string]int
+}
+
+func (c *SafeCounter) Inc(key string) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.v[key]++
+}
+
+func (c *SafeCounter) Get(key string) int {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    return c.v[key]
+}
+```
+
+### Use Channels When
+
+```go
+// Communicating between goroutines / coordinating work
+func pipeline(ctx context.Context, input []int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for _, n := range input {
+            select {
+            case out <- transform(n):
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+```
+
+### Decision Guide
+
+| Scenario | Use |
+|----------|-----|
+| Guarding shared state | `sync.Mutex` or `sync.RWMutex` |
+| Passing ownership of data | Channels |
+| Coordinating goroutine lifecycle | `context.Context` + channels |
+| Waiting for N goroutines | `sync.WaitGroup` or `errgroup` |
+| One-time initialization | `sync.Once` |
+| Concurrent map access | `sync.Map` (high read, low write) |
+
+---
+
+## sync.Once for Initialization
+
+```go
+type Client struct {
+    once sync.Once
+    conn *grpc.ClientConn
+    err  error
+}
+
+func (c *Client) connection() (*grpc.ClientConn, error) {
+    c.once.Do(func() {
+        // requires: "google.golang.org/grpc/credentials/insecure"
+        c.conn, c.err = grpc.Dial("localhost:50051",
+            grpc.WithTransportCredentials(insecure.NewCredentials()))
+    })
+    return c.conn, c.err
+}
+```
+
+---
+
+## Rate Limiting
+
+```go
+func rateLimited(ctx context.Context, items []Item, rps int) error {
+    limiter := rate.NewLimiter(rate.Limit(rps), 1)
+
+    for _, item := range items {
+        if err := limiter.Wait(ctx); err != nil {
+            return fmt.Errorf("rate limiter: %w", err)
+        }
+        if err := process(ctx, item); err != nil {
+            return fmt.Errorf("processing item %s: %w", item.ID, err)
+        }
+    }
+    return nil
+}
+```

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

@@ -0,0 +1,129 @@
+# Go Issue Detection
+
+Grep and regex patterns for finding common Go issues. Reference from main SKILL.md.
+
+## Error Handling Detection
+
+### Unchecked Errors
+
+```bash
+# Find ignored error returns (blank identifier)
+grep -rn ', _ := ' --include='*.go' .
+grep -rn ', _ = ' --include='*.go' .
+
+# Find bare error returns without wrapping
+grep -rn 'return.*err$' --include='*.go' . | grep -v 'fmt.Errorf' | grep -v ':= err'
+
+# Find deferred calls that return errors (Close, Flush, Sync)
+grep -rn 'defer.*\.Close()' --include='*.go' .
+grep -rn 'defer.*\.Flush()' --include='*.go' .
+```
+
+### Missing Error Context
+
+```bash
+# Find raw error returns (no wrapping)
+grep -rn 'return nil, err$' --include='*.go' .
+grep -rn 'return err$' --include='*.go' .
+```
+
+---
+
+## Concurrency Detection
+
+### Goroutine Without Context
+
+```bash
+# Find goroutines that don't reference ctx
+grep -rn 'go func()' --include='*.go' .
+
+# Find goroutines without done/cancel/ctx
+grep -B5 -A10 'go func' --include='*.go' . | grep -L 'ctx\|done\|cancel\|errgroup'
+```
+
+### Potential Goroutine Leaks
+
+```bash
+# Find unbuffered channel creation followed by goroutine
+grep -rn 'make(chan ' --include='*.go' . | grep -v ', [0-9]'
+
+# Find goroutines with infinite loops
+grep -A5 'go func' --include='*.go' . | grep 'for {'
+```
+
+---
+
+## Interface Detection
+
+### Empty Interface Usage
+
+```bash
+# Find empty interface (pre-1.18 style)
+grep -rn 'interface{}' --include='*.go' .
+
+# Find any type (1.18+ style) - may be intentional, review context
+grep -rn '\bany\b' --include='*.go' . | grep -v '_test.go' | grep -v 'vendor/'
+```
+
+### Large Interfaces
+
+```bash
+# Find interface declarations and count methods (interfaces > 5 methods)
+grep -B1 -A20 'type.*interface {' --include='*.go' .
+```
+
+---
+
+## Panic Detection
+
+### Panic in Library Code
+
+```bash
+# Find panic calls outside main/test
+grep -rn 'panic(' --include='*.go' . | grep -v '_test.go' | grep -v 'main.go'
+
+# Find log.Fatal (calls os.Exit) in library code
+grep -rn 'log.Fatal' --include='*.go' . | grep -v 'main.go' | grep -v '_test.go'
+
+# Find os.Exit in library code
+grep -rn 'os.Exit' --include='*.go' . | grep -v 'main.go' | grep -v '_test.go'
+```
+
+---
+
+## init() Detection
+
+```bash
+# Find all init functions
+grep -rn '^func init()' --include='*.go' .
+
+# Find init functions with side effects (network, file, global state)
+grep -A10 '^func init()' --include='*.go' . | grep -E 'http\.|sql\.|os\.|Open|Dial|Connect'
+```
+
+---
+
+## Mutex and Race Detection
+
+```bash
+# Find mutex passed by value (function params with Mutex, not pointer)
+grep -rn 'func.*sync\.Mutex[^*]' --include='*.go' .
+
+# Find Lock without corresponding Unlock
+grep -rn '\.Lock()' --include='*.go' . | grep -v 'defer.*Unlock'
+
+# Find RLock without RUnlock
+grep -rn '\.RLock()' --include='*.go' . | grep -v 'defer.*RUnlock'
+```
+
+---
+
+## Map and Slice Safety
+
+```bash
+# Find uninitialized map declarations (potential nil map panic)
+grep -rn 'var.*map\[' --include='*.go' . | grep -v 'make\|:='
+
+# Find slice append without pre-allocation hint
+grep -rn 'append(' --include='*.go' . | head -20
+```

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
+}
+```