claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/stack-agents/go/references/context-propagation.md

@@ -0,0 +1,317 @@
+# Context Propagation
+
+> Reference document for go-concurrency-reviewer. Loaded on demand via Read tool.
+
+## Context Creation
+
+| Function | Use When | Example |
+|----------|----------|---------|
+| `context.Background()` | Entry points: main, init, top-level | `main()`, `TestMain()` |
+| `context.TODO()` | Temporary placeholder during refactoring | Grep for these and replace |
+| `context.WithCancel(parent)` | Explicit cancellation needed | Worker lifecycle |
+| `context.WithTimeout(parent, d)` | Operation has time budget | HTTP client call |
+| `context.WithDeadline(parent, t)` | Absolute deadline | "Must complete by 5pm" |
+| `context.WithValue(parent, k, v)` | Request-scoped metadata | Request ID, auth token |
+| `context.WithoutCancel(parent)` | Detach from parent deadline (Go 1.21+) | Async cleanup after response |
+
+```go
+// Entry point — Background
+func main() {
+    ctx := context.Background()
+    if err := run(ctx); err != nil {
+        log.Fatal(err)
+    }
+}
+
+// Cancellation — stops all child goroutines
+func (s *Service) Start(ctx context.Context) {
+    ctx, cancel := context.WithCancel(ctx)
+    defer cancel() // always defer cancel
+
+    go s.worker(ctx)
+    go s.monitor(ctx)
+
+    <-ctx.Done()
+}
+
+// Timeout — for bounded operations
+func (c *Client) Fetch(ctx context.Context, url string) (*Response, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel() // release resources even if completed early
+
+    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+    if err != nil {
+        return nil, err
+    }
+    return c.http.Do(req)
+}
+
+// Deadline — absolute time
+func (s *Scheduler) RunBefore(ctx context.Context, deadline time.Time) error {
+    ctx, cancel := context.WithDeadline(ctx, deadline)
+    defer cancel()
+    return s.execute(ctx)
+}
+```
+
+## Cancellation Flow
+
+Cancelling a parent context cancels **all** children. This is the core mechanism for graceful shutdown.
+
+```go
+//       root (Background)
+//        |
+//    parentCtx (WithCancel)
+//      /    \
+//  child1   child2 (WithTimeout)
+//    |         |
+//  child3   child4
+//
+// cancel(parentCtx) → cancels child1, child2, child3, child4
+// cancel(child2)    → cancels child4 only
+
+func example() {
+    root := context.Background()
+
+    parentCtx, parentCancel := context.WithCancel(root)
+    defer parentCancel()
+
+    child1, cancel1 := context.WithCancel(parentCtx)
+    defer cancel1()
+
+    child2, cancel2 := context.WithTimeout(parentCtx, 5*time.Second)
+    defer cancel2()
+
+    // Cancelling parent stops everything
+    parentCancel() // child1.Done() and child2.Done() both fire
+}
+```
+
+## Timeout Patterns
+
+### Server Middleware
+
+```go
+func TimeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            ctx, cancel := context.WithTimeout(r.Context(), timeout)
+            defer cancel()
+            next.ServeHTTP(w, r.WithContext(ctx))
+        })
+    }
+}
+
+// Usage
+mux.Handle("POST /api/upload", TimeoutMiddleware(30*time.Second)(uploadHandler))
+mux.Handle("GET /api/users", TimeoutMiddleware(5*time.Second)(listHandler))
+```
+
+### Client Calls with Per-Request Timeout
+
+```go
+func (c *APIClient) GetUser(ctx context.Context, id int64) (*User, error) {
+    // Respect caller's deadline, but add our own if none exists
+    if _, ok := ctx.Deadline(); !ok {
+        var cancel context.CancelFunc
+        ctx, cancel = context.WithTimeout(ctx, 3*time.Second)
+        defer cancel()
+    }
+
+    req, err := http.NewRequestWithContext(ctx, "GET",
+        fmt.Sprintf("%s/users/%d", c.baseURL, id), nil)
+    if err != nil {
+        return nil, fmt.Errorf("APIClient.GetUser: %w", err)
+    }
+
+    resp, err := c.http.Do(req)
+    if err != nil {
+        if errors.Is(err, context.DeadlineExceeded) {
+            return nil, fmt.Errorf("APIClient.GetUser: %w", domain.ErrTimeout)
+        }
+        return nil, fmt.Errorf("APIClient.GetUser: %w", err)
+    }
+    defer resp.Body.Close()
+
+    var user User
+    if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
+        return nil, fmt.Errorf("APIClient.GetUser: decode: %w", err)
+    }
+    return &user, nil
+}
+```
+
+### Database Query with Timeout
+
+```go
+func (r *Repo) Search(ctx context.Context, query string) ([]*User, error) {
+    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
+    defer cancel()
+
+    rows, err := r.db.Query(ctx,
+        "SELECT id, name, email FROM users WHERE name ILIKE $1 LIMIT 100",
+        "%"+query+"%")
+    if err != nil {
+        if errors.Is(err, context.DeadlineExceeded) {
+            return nil, fmt.Errorf("Repo.Search: query too slow: %w", domain.ErrTimeout)
+        }
+        return nil, fmt.Errorf("Repo.Search: %w", err)
+    }
+    defer rows.Close()
+    // ...
+}
+```
+
+## Context Value Keys
+
+**Always use typed, unexported keys.** Never use strings or built-in types as keys.
+
+```go
+// CORRECT — typed unexported key
+type contextKey struct{}
+
+var requestIDKey = contextKey{}
+
+func WithRequestID(ctx context.Context, id string) context.Context {
+    return context.WithValue(ctx, requestIDKey, id)
+}
+
+func RequestIDFromContext(ctx context.Context) string {
+    id, _ := ctx.Value(requestIDKey).(string)
+    return id
+}
+```
+
+```go
+// WRONG — string key (collisions between packages)
+ctx = context.WithValue(ctx, "request_id", id)
+
+// WRONG — exported key (anyone can overwrite)
+var RequestIDKey = "request_id"
+```
+
+### Common Context Values
+
+```go
+// Each value gets its own key type and accessor pair
+type requestIDKeyType struct{}
+type userIDKeyType struct{}
+type traceIDKeyType struct{}
+
+var (
+    requestIDKey = requestIDKeyType{}
+    userIDKey    = userIDKeyType{}
+    traceIDKey   = traceIDKeyType{}
+)
+
+// Middleware sets values
+func AuthMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        userID := extractUserID(r)
+        ctx := context.WithValue(r.Context(), userIDKey, userID)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Service reads values
+func (s *Service) Process(ctx context.Context) error {
+    userID, _ := ctx.Value(userIDKey).(int64)
+    requestID, _ := ctx.Value(requestIDKey).(string)
+    s.logger.Info("processing",
+        "user_id", userID,
+        "request_id", requestID,
+    )
+    // ...
+}
+```
+
+## context.WithoutCancel (Go 1.21+)
+
+Detach a context from its parent's cancellation while preserving values. Useful for operations that must continue after the parent is cancelled.
+
+```go
+// Async audit logging — must complete even if request is cancelled
+func (h *Handler) Delete(w http.ResponseWriter, r *http.Request) {
+    if err := h.svc.Delete(r.Context(), id); err != nil {
+        respondError(w, err)
+        return
+    }
+
+    // Audit log must succeed even if client disconnects
+    auditCtx := context.WithoutCancel(r.Context()) // keeps values, ignores cancel
+    go h.audit.Log(auditCtx, AuditEvent{
+        Action: "delete",
+        UserID: UserIDFromContext(r.Context()),
+    })
+
+    respondOK(w)
+}
+
+// Cleanup after response — needs its own timeout
+func (s *Service) Process(ctx context.Context) error {
+    result, err := s.doWork(ctx)
+    if err != nil {
+        return err
+    }
+
+    // Cleanup with independent timeout
+    cleanupCtx := context.WithoutCancel(ctx)
+    cleanupCtx, cancel := context.WithTimeout(cleanupCtx, 5*time.Second)
+    defer cancel()
+    s.cleanup(cleanupCtx, result)
+
+    return nil
+}
+```
+
+## Anti-Patterns
+
+### Storing Context in Structs
+
+```go
+// WRONG — context should flow through function calls, not be stored
+type Service struct {
+    ctx context.Context // BAD: stale context, can't be per-request
+}
+
+// CORRECT — context as first parameter
+func (s *Service) Process(ctx context.Context, data Data) error {
+    // ctx is per-request, fresh
+}
+```
+
+### Using context.Background() Deep in Call Stack
+
+```go
+// WRONG — ignores caller's cancellation/deadline
+func (r *Repo) Save(ctx context.Context, u *User) error {
+    _, err := r.db.Exec(context.Background(), query, u.ID) // ignores ctx!
+    return err
+}
+
+// CORRECT — propagate the received context
+func (r *Repo) Save(ctx context.Context, u *User) error {
+    _, err := r.db.Exec(ctx, query, u.ID) // respects caller's deadline
+    return err
+}
+```
+
+### Overloading Context Values
+
+```go
+// WRONG — passing dependencies through context
+ctx = context.WithValue(ctx, "db", db)       // use DI instead
+ctx = context.WithValue(ctx, "logger", log)   // use struct fields instead
+
+// CORRECT — context values are for request-scoped data only
+ctx = context.WithValue(ctx, requestIDKey, reqID) // request ID
+ctx = context.WithValue(ctx, userIDKey, userID)    // authenticated user
+ctx = context.WithValue(ctx, traceIDKey, traceID)  // distributed trace
+```
+
+## When to Use
+
+Apply when reviewing context usage across function boundaries. Flag violations as:
+- **CRITICAL**: Storing context in struct, using `context.Background()` deep in call stack, string context keys
+- **WARNING**: Missing `defer cancel()`, no timeout on external calls, context values for dependencies
+- **SUGGESTION**: Could use `WithoutCancel` for async cleanup, missing deadline check before expensive operation

package/packages/stack-agents/go/references/data-structures.md

@@ -0,0 +1,315 @@
+# Data Structures
+
+> Reference document for go-reviewer. Loaded on demand via Read tool.
+
+## Slices
+
+### Append Semantics
+
+`append` may allocate a new underlying array. **Always reassign** the result.
+
+```go
+// CORRECT — reassign
+s = append(s, item)
+
+// BUG — discards potential new allocation
+func addItem(s []int, item int) {
+    append(s, item) // result not captured!
+}
+```
+
+### Capacity and Growth
+
+```go
+// Pre-allocate when size is known — avoids repeated copying
+users := make([]User, 0, len(ids))
+for _, id := range ids {
+    u, err := repo.FindByID(ctx, id)
+    if err != nil {
+        return nil, err
+    }
+    users = append(users, *u)
+}
+
+// Growth policy: Go runtime doubles small slices, grows ~25% for large ones
+// Check current capacity
+fmt.Println(len(s), cap(s))
+```
+
+### Copy for Safety
+
+Slices share underlying arrays. Copy when you need independent data.
+
+```go
+// DANGEROUS — modifying returned slice affects internal state
+func (c *Cache) GetIDs() []int64 {
+    return c.ids // caller can modify c.ids!
+}
+
+// SAFE — return a copy
+func (c *Cache) GetIDs() []int64 {
+    result := make([]int64, len(c.ids))
+    copy(result, c.ids)
+    return result
+}
+
+// SAFE — slices.Clone (Go 1.21+)
+func (c *Cache) GetIDs() []int64 {
+    return slices.Clone(c.ids)
+}
+```
+
+### Nil vs Empty Slices
+
+```go
+var s []int          // nil slice:  s == nil, len(s) == 0, json → null
+s = []int{}          // empty slice: s != nil, len(s) == 0, json → []
+s = make([]int, 0)   // empty slice: s != nil, len(s) == 0, json → []
+```
+
+**Decision table — nil vs empty:**
+
+| Context | Use | Why |
+|---------|-----|-----|
+| JSON API response | `[]int{}` or `make` | Clients expect `[]`, not `null` |
+| Internal return, no results | `nil` | Idiomatic, `len`/`append` work on nil |
+| Struct field default | `nil` (zero value) | Initialize on first use |
+| Test assertion | Be explicit | `assert.Nil` vs `assert.Empty` differ |
+
+### Slice Tricks
+
+```go
+// Delete element at index i (preserves order)
+s = slices.Delete(s, i, i+1) // Go 1.21+
+// or: s = append(s[:i], s[i+1:]...)
+
+// Delete without preserving order (fast)
+s[i] = s[len(s)-1]
+s = s[:len(s)-1]
+
+// Filter in-place
+s = slices.DeleteFunc(s, func(v int) bool {
+    return v < 0
+})
+
+// Deduplicate sorted slice
+slices.Sort(s)
+s = slices.Compact(s)
+```
+
+## Maps
+
+### Initialization
+
+```go
+// Must initialize before writing — nil map write panics!
+var m map[string]int
+m["key"] = 1 // PANIC: assignment to entry in nil map
+
+// CORRECT ways to initialize
+m := make(map[string]int)
+m := make(map[string]int, expectedSize) // pre-size hint
+m := map[string]int{"key": 1}           // literal
+```
+
+### Iteration Order
+
+Map iteration order is **randomized** by the Go runtime. Never depend on order.
+
+```go
+// If you need ordered keys:
+keys := make([]string, 0, len(m))
+for k := range m {
+    keys = append(keys, k)
+}
+slices.Sort(keys)
+for _, k := range keys {
+    fmt.Println(k, m[k])
+}
+```
+
+### Concurrency
+
+| Operation | Safe without sync? |
+|-----------|-------------------|
+| Concurrent reads (no writes) | Yes |
+| Concurrent read + write | NO — data race, may crash |
+| Concurrent writes | NO — data race, may crash |
+
+```go
+// WRONG — data race
+go func() { m["a"] = 1 }()
+go func() { _ = m["a"] }()
+
+// CORRECT — mutex protection
+type SafeMap struct {
+    mu sync.RWMutex
+    m  map[string]int
+}
+
+func (sm *SafeMap) Get(key string) (int, bool) {
+    sm.mu.RLock()
+    defer sm.mu.RUnlock()
+    v, ok := sm.m[key]
+    return v, ok
+}
+
+func (sm *SafeMap) Set(key string, value int) {
+    sm.mu.Lock()
+    defer sm.mu.Unlock()
+    sm.m[key] = value
+}
+```
+
+### sync.Map
+
+Use **only** when one of these applies:
+- Append-only (keys written once, read many)
+- Disjoint key sets per goroutine
+
+**Do not** use sync.Map as a general concurrent map — it's slower for mixed read/write workloads.
+
+```go
+var cache sync.Map
+
+// Store
+cache.Store("key", value)
+
+// Load
+if v, ok := cache.Load("key"); ok {
+    user := v.(*User)
+}
+
+// LoadOrStore — atomic get-or-set
+actual, loaded := cache.LoadOrStore("key", newValue)
+```
+
+## Arrays vs Slices
+
+| Feature | Array | Slice |
+|---------|-------|-------|
+| Type | Value type (copied on assignment) | Reference type (shares backing array) |
+| Size | Fixed, part of type: `[5]int` | Dynamic: `[]int` |
+| Comparison | `==` works | `==` doesn't compile (use `slices.Equal`) |
+| Function args | Copied entirely | Header only (24 bytes) |
+| Common use | Rare (crypto hashes, IP addrs) | Everywhere |
+
+```go
+// Array — value type, full copy
+a := [3]int{1, 2, 3}
+b := a         // b is an independent copy
+b[0] = 99      // a[0] is still 1
+
+// Slice — reference type, shared backing
+s := []int{1, 2, 3}
+t := s          // t shares same backing array
+t[0] = 99       // s[0] is now 99!
+```
+
+## Generics (Go 1.18+)
+
+### Type Constraints
+
+```go
+// Built-in constraints
+func Max[T cmp.Ordered](a, b T) T {
+    if a > b {
+        return a
+    }
+    return b
+}
+
+// Custom constraint
+type Number interface {
+    ~int | ~int32 | ~int64 | ~float32 | ~float64
+}
+
+func Sum[T Number](values []T) T {
+    var total T
+    for _, v := range values {
+        total += v
+    }
+    return total
+}
+```
+
+### Generic Data Structures
+
+```go
+type Set[T comparable] struct {
+    m map[T]struct{}
+}
+
+func NewSet[T comparable](items ...T) *Set[T] {
+    s := &Set[T]{m: make(map[T]struct{}, len(items))}
+    for _, item := range items {
+        s.m[item] = struct{}{}
+    }
+    return s
+}
+
+func (s *Set[T]) Contains(item T) bool {
+    _, ok := s.m[item]
+    return ok
+}
+
+func (s *Set[T]) Add(item T) {
+    s.m[item] = struct{}{}
+}
+```
+
+### When to Use Generics
+
+| Use generics | Don't use generics |
+|--------------|-------------------|
+| Collection utilities (Map, Filter, Reduce) | Business logic (unclear types) |
+| Data structures (Set, Queue, Stack) | When `any` or `interface{}` suffices |
+| Algorithms that work on multiple types | When only 1-2 types will ever be used |
+| Type-safe wrappers | When it hurts readability |
+
+## Pointer Types
+
+**Decision table — pointer vs value:**
+
+| Condition | Use Pointer | Use Value |
+|-----------|-------------|-----------|
+| Struct > 64 bytes | Yes — avoid copy cost | |
+| Needs mutation | Yes | |
+| Implements interface with pointer receiver | Yes | |
+| Optional / nullable field | Yes (`*string`) | |
+| Small struct (< 4 fields, no slices/maps) | | Yes |
+| Immutable data | | Yes |
+| Map key | | Yes (pointers can't be map keys) |
+| Concurrency without sync | | Yes (value copy is safe) |
+
+```go
+// Pointer — large struct, needs mutation
+func (s *Service) UpdateUser(ctx context.Context, user *User) error {
+    user.UpdatedAt = time.Now()
+    return s.repo.Save(ctx, user)
+}
+
+// Value — small, immutable
+type Point struct {
+    X, Y float64
+}
+
+func Distance(a, b Point) float64 {
+    dx := a.X - b.X
+    dy := a.Y - b.Y
+    return math.Sqrt(dx*dx + dy*dy)
+}
+
+// Optional fields
+type UpdateInput struct {
+    Name  *string `json:"name,omitempty"`  // nil = don't update
+    Email *string `json:"email,omitempty"` // nil = don't update
+}
+```
+
+## When to Use
+
+Apply when reviewing Go data structure usage. Flag violations as:
+- **CRITICAL**: Writing to nil map, not reassigning append result, concurrent map access without sync
+- **WARNING**: Returning internal slice without copy, using sync.Map for general concurrent access
+- **SUGGESTION**: Missing pre-allocation, using arrays instead of slices, unnecessary pointer for small types