claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/stack-agents/go/references/samber-lo.md

@@ -0,0 +1,260 @@
+# samber/lo — Generic Collection Utilities
+
+> Reference document for go-reviewer. Loaded on demand via Read tool.
+> Upstream: https://github.com/samber/lo
+
+## What It Is
+
+500+ generic helpers for slices, maps, channels, strings, and tuples. Shaped like Lodash / Ramda, but generics-native (Go 1.18+). Not a replacement for the stdlib `slices` (Go 1.21+) and `maps` packages — it layers on top where stdlib is missing something or where readability wins.
+
+## High-Frequency Functions
+
+### Transform
+
+```go
+import "github.com/samber/lo"
+
+// Map: T -> U
+names := lo.Map(users, func(u User, _ int) string {
+    return u.Name
+})
+
+// Filter: keep elements matching predicate
+active := lo.Filter(users, func(u User, _ int) bool {
+    return u.Status == StatusActive
+})
+
+// FilterMap: filter + map in one pass (no intermediate slice)
+emails := lo.FilterMap(users, func(u User, _ int) (string, bool) {
+    if u.Email == "" {
+        return "", false
+    }
+    return strings.ToLower(u.Email), true
+})
+
+// FlatMap: T -> []U, then flatten
+tagPairs := lo.FlatMap(posts, func(p Post, _ int) []string {
+    return p.Tags
+})
+
+// ForEach: side-effect iteration (no return)
+lo.ForEach(users, func(u User, _ int) {
+    log.Printf("user: %s", u.Name)
+})
+
+// Reduce
+total := lo.Reduce(prices, func(acc float64, p Price, _ int) float64 {
+    return acc + p.Amount
+}, 0.0)
+```
+
+### Dedup / Partition
+
+```go
+// Uniq — preserves order
+ids := lo.Uniq([]int{1, 2, 2, 3, 1}) // [1 2 3]
+
+// UniqBy — dedupe by key
+users := lo.UniqBy(allUsers, func(u User) int64 { return u.ID })
+
+// Chunk — split into fixed-size batches (last chunk may be shorter)
+batches := lo.Chunk(items, 100) // [][]Item
+
+// Partition — split by predicate into (matched, rest)
+admins, others := lo.FilterReject(users, func(u User, _ int) bool {
+    return u.Role == RoleAdmin
+})
+```
+
+### Index / Group
+
+```go
+// GroupBy — map[K][]V
+byStatus := lo.GroupBy(users, func(u User) Status { return u.Status })
+
+// KeyBy — map[K]V (later wins on collision; use UniqBy first if that matters)
+byID := lo.KeyBy(users, func(u User) int64 { return u.ID })
+
+// Associate — map[K]V via (key, value) callback
+nameToEmail := lo.Associate(users, func(u User) (string, string) {
+    return u.Name, u.Email
+})
+```
+
+### Control Flow
+
+```go
+// Ternary — expression-form conditional
+status := lo.Ternary(isActive, "active", "inactive")
+
+// If / ElseIf / Else — chainable conditional
+label := lo.If(age < 13, "child").
+    ElseIf(age < 20, "teen").
+    ElseIf(age < 65, "adult").
+    Else("senior")
+
+// Coalesce — first non-zero value
+name := lo.Coalesce(u.DisplayName, u.Username, "anonymous")
+
+// CoalesceOrEmpty — same but returns zero value instead of bool
+```
+
+### Error Ergonomics
+
+```go
+// Must — panic on error. init/main only; never in request handlers.
+cfg := lo.Must(loadConfig())
+
+// Must0 — for funcs returning only error: `lo.Must0(db.Ping())`
+
+// Try — run a fn, catch panic, return (value, error)
+value, err := lo.Try(func() error {
+    doSomethingThatMightPanic()
+    return nil
+})
+
+// Attempt — retry up to N times or until fn returns nil error
+iter, err := lo.Attempt(3, func(i int) error {
+    return callFlakeyAPI()
+})
+
+// AttemptWithDelay / AttemptWhile for backoff + predicate-controlled loops
+
+// TryWithErrorValue — recover panic payload as `any` (not just error)
+value, errOrAny := lo.TryWithErrorValue(func() error { ... })
+```
+
+## When to Prefer Stdlib
+
+Go 1.21 shipped `slices` and `maps` packages covering the common cases. Prefer stdlib when:
+
+| Task | Stdlib | samber/lo |
+|------|--------|-----------|
+| Find index | `slices.Index(s, v)` | `lo.IndexOf(s, v)` |
+| Contains | `slices.Contains(s, v)` | `lo.Contains(s, v)` |
+| Reverse (in-place) | `slices.Reverse(s)` | `lo.Reverse(s)` (copies) |
+| Sort | `slices.Sort(s)` / `SortFunc` | `lo.Sort` — don't use |
+| Delete at index | `slices.Delete(s, i, j)` | not equivalent |
+| Binary search | `slices.BinarySearch` | no equivalent |
+| Get map keys | `maps.Keys(m)` (iter.Seq) | `lo.Keys(m)` (slice) |
+| Get map values | `maps.Values(m)` (iter.Seq) | `lo.Values(m)` (slice) |
+
+Rule of thumb: if stdlib has it, use stdlib. Use lo for transforms (`Map`/`Filter`/`Reduce`), grouping (`GroupBy`/`KeyBy`), and control flow helpers that stdlib doesn't have.
+
+## Performance Caveats
+
+`lo.Map` allocates a new slice sized to `len(input)` — fine. But chained calls allocate an intermediate slice at every step:
+
+```go
+// 3 allocations: filtered, mapped, uniqued
+result := lo.Uniq(lo.Map(lo.Filter(xs, keep), transform))
+
+// 1 allocation with FilterMap
+result := lo.FilterMap(xs, func(x T, _ int) (U, bool) {
+    if !keep(x, 0) { return *new(U), false }
+    return transform(x, 0), true
+})
+```
+
+`lo.Map` takes `func(T, int) U` — that closure can escape to the heap if it captures a variable. For hot paths, benchmark against a manual loop:
+
+```go
+names := make([]string, 0, len(users))
+for _, u := range users {
+    names = append(names, u.Name)
+}
+```
+
+For 3-element slices, the loop is faster and clearer than `lo.Map`. For 10k+ elements, both perform comparably — readability wins.
+
+`lo.Contains` is O(n) — if you do it in a loop, convert the slice to a map once: `seen := lo.Associate(xs, func(x T) (T, struct{}) { return x, struct{}{} })`.
+
+## Parallel Variants (lo/parallel subpackage)
+
+```go
+import "github.com/samber/lo/parallel"
+
+// Fan out Map across all workers (runtime.NumCPU by default)
+results := parallel.Map(urls, func(url string, _ int) *Response {
+    return fetch(url) // blocking I/O
+})
+```
+
+Use when the callback is I/O-bound (HTTP, DB). For CPU-bound work, the overhead usually isn't worth it unless `len(input) > 1000`. `parallel.Map` does not preserve order of execution but preserves order of the output slice. It does NOT bound the goroutine count — for 100k elements, build your own worker pool.
+
+## Anti-Patterns
+
+### Using lo.Must in Request Handlers
+
+```go
+// WRONG — panics the whole server process
+func (h *Handler) Get(w http.ResponseWriter, r *http.Request) {
+    user := lo.Must(h.repo.Find(r.Context(), id))
+    // ...
+}
+
+// RIGHT
+user, err := h.repo.Find(r.Context(), id)
+if err != nil {
+    http.Error(w, err.Error(), http.StatusInternalServerError)
+    return
+}
+```
+
+`lo.Must` is for `init()`, `main()`, and test helpers. Nowhere else.
+
+### Using lo for Trivial Cases
+
+```go
+// WRONG — less clear than a 3-line loop
+isUnique := lo.Uniq([]int{a, b, c})
+if len(isUnique) == 3 { ... }
+
+// RIGHT
+if a != b && b != c && a != c { ... }
+```
+
+### lo.ForEach When You Don't Need It
+
+```go
+// Noise — for _, x := range is clearer
+lo.ForEach(users, func(u User, _ int) {
+    log.Printf("%s", u.Name)
+})
+
+// Prefer
+for _, u := range users {
+    log.Printf("%s", u.Name)
+}
+```
+
+`ForEach` is useful in expression position (inside a builder) — not as a replacement for `for range`.
+
+### Chaining With Shared Closure State
+
+```go
+// Risky — closure captures `total` which is shared across goroutines if parallel variant
+var total int
+lo.ForEach(xs, func(x int, _ int) { total += x })
+
+// Prefer reduce for clarity and purity
+total := lo.Reduce(xs, func(a, x, _ int) int { return a + x }, 0)
+```
+
+## Review Checklist
+
+When reviewing code using samber/lo, flag:
+
+- **CRITICAL** — `lo.Must` / `lo.Must0` in request handlers, middleware, or goroutines that don't own the process (will panic the server)
+- **WARNING** — Chained `Filter` → `Map` → `Uniq` on large inputs (replace with `FilterMap` + `Uniq`, or a single loop)
+- **WARNING** — `parallel.Map` over unbounded input (goroutine explosion — use a bounded worker pool)
+- **WARNING** — `lo.Contains` in a loop (O(n*m); convert outer set to map once)
+- **SUGGESTION** — Using lo where stdlib `slices` / `maps` covers it (slices.Contains, slices.Index, etc.)
+- **SUGGESTION** — 3-line loop rewritten as lo chain for no readability gain
+
+## Further Reading
+
+- Upstream docs: https://github.com/samber/lo (README lists all 500+ helpers)
+- stdlib `slices`: https://pkg.go.dev/slices
+- stdlib `maps`: https://pkg.go.dev/maps
+- Parallel subpackage: https://github.com/samber/lo/tree/master/parallel

package/packages/stack-agents/go/references/samber-oops.md

@@ -0,0 +1,200 @@
+# samber/oops — Structured Errors with Stack Traces
+
+> Reference document for go-reviewer, go-error-reviewer. Loaded on demand via Read tool.
+> Upstream: https://github.com/samber/oops
+
+## What Stdlib Errors Don't Give You
+
+`errors.New` + `fmt.Errorf("ctx: %w", err)` get you:
+
+- An error message
+- An unwrap chain (`errors.Is` / `errors.As`)
+
+That's it. You don't get: stack traces, domain codes, request IDs, user-facing hints, owner/team routing, or structured key-value context. Every observability backend (Sentry, Datadog, New Relic) wants those. `samber/oops` adds them via a builder API that composes with `errors.Is` and `errors.As` so you don't lose stdlib interop.
+
+## Core API
+
+```go
+import "github.com/samber/oops"
+
+// Create
+err := oops.
+    Code("USER_NOT_FOUND").
+    In("UserService.FindByID").
+    With("user_id", userID).
+    Errorf("user %d not found", userID)
+
+// Wrap — adds attributes to an existing error
+err := oops.
+    In("OrderService.Create").
+    With("order_id", orderID).
+    User(currentUser.ID, "email", currentUser.Email).
+    Wrap(repoErr)
+
+// Wrap with a fresh message
+err := oops.
+    Trace(traceID).
+    Wrapf(repoErr, "could not persist order %d", orderID)
+```
+
+All builder methods return an `oops.OopsErrorBuilder` — chain freely, call `Errorf`/`Wrap`/`Wrapf`/`New` last.
+
+## Attribute Methods (highlights)
+
+| Method | Purpose | APM field it usually maps to |
+|--------|---------|-----------------------------|
+| `.Code("USER_NOT_FOUND")` | Stable machine-readable error key | `error.code` |
+| `.In("pkg.Service.Method")` | Domain / subsystem the error came from | `error.domain` |
+| `.Tags("auth", "critical")` | Free-form labels | `error.tags` |
+| `.With("key", value)` | Arbitrary structured context | `error.context.*` |
+| `.User(id, "email", x)` | User identity attached to error | `user.id`, `user.email` |
+| `.Tenant(id, "name", x)` | Tenant / org identity | `tenant.id` |
+| `.Request(req)` | Capture `*http.Request` (method, URL, headers) | `http.*` |
+| `.Trace(traceID)` | Distributed tracing correlation | `trace.id` |
+| `.Hint("rotate API key")` | Operator-facing remediation hint | `error.hint` |
+| `.Public("Account not found")` | User-safe message for HTTP body | `error.public_message` |
+| `.Owner("payments-team")` | Team/owner routing | `error.owner` |
+| `.Duration(elapsed)` | How long the failing op ran | `error.duration_ms` |
+| `.Time(t)` | Override capture timestamp | `error.timestamp` |
+
+## Stack Traces
+
+Stack is captured automatically at the *first* `Errorf`/`Wrap`/`Wrapf`/`New` in a chain — not at every wrap. Depth is capped by `oops.StackTraceMaxDepth` (default 10 frames); set to 0 to disable:
+
+```go
+oops.StackTraceMaxDepth = 0 // disable for hot paths if profiling shows cost
+```
+
+Recover frames via `oopsErr.Stacktrace()` (returns `oops.OopsStackTrace`, which implements `fmt.Formatter`).
+
+## Extraction for Logging / APM
+
+```go
+import (
+    "errors"
+    "log/slog"
+    "github.com/samber/oops"
+)
+
+func logError(err error) {
+    var oe oops.OopsError
+    if errors.As(err, &oe) {
+        slog.Error("operation failed",
+            "code",        oe.Code(),
+            "domain",      oe.Domain(),
+            "tags",        oe.Tags(),
+            "context",     oe.Context(),
+            "hint",        oe.Hint(),
+            "owner",       oe.Owner(),
+            "user",        oe.User(),
+            "trace_id",    oe.Trace(),
+            "stacktrace",  oe.Stacktrace(),
+            "error",       err,
+        )
+        return
+    }
+    slog.Error("operation failed", "error", err)
+}
+
+// Or use the built-in slog attrs helper:
+slog.Error("operation failed", slog.Any("error", oops.ToMap(err)))
+```
+
+`oops.ToMap(err)` walks the full chain and merges attributes (innermost wins on key conflict — but make keys unique anyway).
+
+## HTTP Boundary: Public vs Private
+
+Never expose internal error messages over HTTP. Use `.Public(msg)` to attach a user-facing string, keep the verbose message private:
+
+```go
+err := oops.
+    Code("RATE_LIMIT").
+    Public("Too many requests. Try again in a minute.").
+    With("ip", clientIP).
+    With("window", "60s").
+    New("rate limit hit: %d req/min from %s", reqCount, clientIP)
+
+// In middleware:
+var oe oops.OopsError
+if errors.As(err, &oe) {
+    http.Error(w, oe.Public(), http.StatusTooManyRequests) // safe message
+    logError(err)                                          // internal detail
+    return
+}
+http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+```
+
+## errors.Is / errors.As Compatibility
+
+`oops.Wrap` preserves the chain; stdlib inspection keeps working.
+
+```go
+sentinel := errors.New("not found")
+err := oops.Code("USER_NOT_FOUND").Wrap(sentinel)
+
+errors.Is(err, sentinel)        // true
+errors.As(err, &oops.OopsError{}) // true — extract attributes
+```
+
+Match on `Code` for domain logic, `errors.Is` for sentinel identity. Don't match on message text — that's fragile across wraps.
+
+```go
+// Match on code — stable
+if oops.GetCode(err) == "USER_NOT_FOUND" {
+    return http.StatusNotFound
+}
+
+// Match on sentinel — stable
+if errors.Is(err, domain.ErrNotFound) {
+    return http.StatusNotFound
+}
+```
+
+## Comparison: stdlib vs pkg/errors vs samber/oops
+
+| Feature | stdlib `errors` | `pkg/errors` | `samber/oops` |
+|---------|-----------------|--------------|---------------|
+| Wrap + message | `fmt.Errorf %w` | `errors.Wrap` | `.Wrapf` / `.Wrap` |
+| Stack trace | No | Yes (always-on) | Yes (configurable) |
+| Structured context (`key=value`) | No | No | Yes (`.With`) |
+| Domain code | Sentinels only | Sentinels only | Yes (`.Code`) |
+| User-safe message | Manual | Manual | Yes (`.Public`) |
+| User / tenant attribution | No | No | Yes (`.User`, `.Tenant`) |
+| APM-shape serialization | Manual | Manual | `oops.ToMap` |
+| Maintenance status | Stdlib | Archived upstream | Active |
+
+`pkg/errors` is archived; new code should use stdlib or oops, not pkg/errors.
+
+## When NOT to Use oops
+
+- **Library code with a public API** — don't force the oops dependency on consumers. Return stdlib errors; let callers add context.
+- **Small internal tools** — `fmt.Errorf("ctx: %w", err)` is enough.
+- **Inside a hot loop** — builder allocates; stack capture is non-trivial. Measure first.
+- **When a sentinel + `errors.Is` is cleaner** — oops complements sentinels, doesn't replace them.
+
+## Common Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---------|---------|-----|
+| Wrapping an oops error with oops again | Duplicate stack traces, attribute shadowing | Wrap once at the deepest point; add attributes elsewhere |
+| Returning `nil` from a builder by accident | Chain like `.Code("X").With(...)` with no terminator leaks an `*OopsErrorBuilder` into the return | Always end with `.Errorf` / `.Wrap` / `.New` |
+| Sending `.Public()` absent | HTTP response leaks internal detail | Default-deny at the HTTP boundary — if `.Public()` is empty, use a generic string |
+| Expecting `errors.Is` to match on `Code` | `Code` is a separate attribute, not a sentinel | Use `oops.GetCode(err)` |
+| Relying on stack trace after serializing over the wire | Stacks don't survive JSON → new process | Log at the origin; pass only structured context over the wire |
+
+## Review Checklist
+
+When reviewing code using samber/oops, flag:
+
+- **CRITICAL** — Internal error returned directly to HTTP response without `.Public()` (info leak)
+- **CRITICAL** — `fmt.Sprintf` with user input used as `.With(key, userInput)` where `key` is dynamic (cardinality explosion in APM)
+- **WARNING** — `oops` used in library code exported to other modules (forces dep on consumers)
+- **WARNING** — Double-wrapping: `oops.Wrap` applied to an already-oops error at every layer (noise + duplicate stacks)
+- **WARNING** — `.Code` values not stable / not centralized (string drift across files)
+- **SUGGESTION** — Consider `.Owner("team")` for multi-team projects so APM routes alerts correctly
+
+## Further Reading
+
+- Upstream docs: https://github.com/samber/oops
+- `errors` stdlib deep dive: `packages/stack-agents/go/references/error-inspection.md`
+- Wrapping conventions: `packages/stack-agents/go/references/error-wrapping.md`