@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/lit-code/references/go/error-handling.md

@@ -0,0 +1,359 @@
+# Error Handling
+
+Typed errors, wrap chains, `errors.Is` / `errors.As`, no panic in libraries, resource cleanup. Go errors look simple and are full of footguns. This document is the canonical set of moves.
+
+---
+
+## The five rules
+
+1. **Every error is wrapped on the way up, with `%w`, with context.** Never `return err` from a non-trivial site.
+2. **Compare with `errors.Is`, not `==`.** Wrap chains break `==`. The `errorlint` linter forbids `==` on errors.
+3. **Cast with `errors.As`, not type assertion.** Same reason.
+4. **`panic` is reserved for programmer errors.** Library code never panics on user input or environment failures. Use `(T, error)`.
+5. **Resources released via `defer` immediately after acquisition.** No "I'll add it later".
+
+---
+
+## Sentinel errors — for invariant programmatic checks
+
+```go
+package domain
+
+import "errors"
+
+var (
+    ErrInvalidEmail   = errors.New("domain: invalid email")
+    ErrInvalidPhone   = errors.New("domain: invalid phone")
+    ErrInvalidAge     = errors.New("domain: invalid age")
+)
+
+func NewEmail(s string) (Email, error) {
+    if !emailRe.MatchString(s) {
+        return Email{}, fmt.Errorf("email %q: %w", s, ErrInvalidEmail)
+    }
+    return Email{raw: strings.ToLower(s)}, nil
+}
+```
+
+Caller branches on identity:
+
+```go
+email, err := domain.NewEmail(input)
+if errors.Is(err, domain.ErrInvalidEmail) {
+    return c.JSON(400, gin.H{"error": "email format"})
+}
+```
+
+`errors.Is` walks the wrap chain. `err == domain.ErrInvalidEmail` would have failed because `fmt.Errorf` wrapped it.
+
+---
+
+## Typed errors — when you need structured data
+
+When callers need fields off the error (the offending value, the failing field name, the upstream HTTP status):
+
+```go
+type ValidationError struct {
+    Field   string
+    Value   string
+    Rule    string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation: %s=%q failed %s", e.Field, e.Value, e.Rule)
+}
+
+// Optional: identity sentinel for errors.Is comparisons
+var ErrValidation = errors.New("validation")
+
+func (e *ValidationError) Is(target error) bool {
+    return target == ErrValidation
+}
+```
+
+Caller:
+
+```go
+err := svc.Save(ctx, user)
+
+var vErr *ValidationError
+if errors.As(err, &vErr) {
+    // vErr.Field, vErr.Rule are available
+    c.JSON(400, gin.H{"field": vErr.Field, "rule": vErr.Rule})
+    return
+}
+```
+
+**`errors.As` requires a non-nil pointer-to-pointer.** Almost always the type is `*ConcreteError`. Forgetting the leading `*` is the most common bug here.
+
+---
+
+## Wrapping — `%w` is mandatory
+
+```go
+// BAD — drops context
+return err
+
+// BAD — drops the error chain (errors.Is/As stops working)
+return fmt.Errorf("failed to save user: %v", err)
+
+// GOOD — preserves chain via %w
+return fmt.Errorf("save user %s: %w", userID, err)
+```
+
+The `errorlint` linter catches `%v` where `%w` was meant. **Wrap once per layer**, with the minimum useful context:
+
+```
+api/handler:  "create user request: %w"
+   service:   "validate inputs: %w"
+      domain: "email %q: %w"
+```
+
+Each frame adds one fact, not a duplicate. The top-level error message reads as a path: `create user request: validate inputs: email "foo": domain: invalid email`.
+
+### `errors.Join` — multiple errors at once
+
+```go
+// Validate all fields, collect all errors
+var errs []error
+if _, err := NewEmail(req.Email); err != nil {
+    errs = append(errs, fmt.Errorf("email: %w", err))
+}
+if _, err := NewUsername(req.Username); err != nil {
+    errs = append(errs, fmt.Errorf("username: %w", err))
+}
+if len(errs) > 0 {
+    return errors.Join(errs...)
+}
+```
+
+`errors.Is` still walks each joined error. Use when reporting batch validation, not for "wrap two unrelated errors".
+
+---
+
+## Panics — when allowed, when banned
+
+**Banned**:
+
+- Anywhere a `(T, error)` could be returned.
+- Inside HTTP handlers (gin's `Recovery` middleware catches them, but you've already lost the error context).
+- Inside any goroutine that survives request lifetime.
+
+**Allowed** (with documentation):
+
+- Map literal init at package level: `var statusNames = map[Status]string{...}` followed by a `func init()` that panics if a const has no name. Catches the bug at startup, not runtime.
+- The `must*` convention for genuinely unrecoverable startup:
+  ```go
+  func MustParseURL(s string) *url.URL {
+      u, err := url.Parse(s)
+      if err != nil { panic(err) }
+      return u
+  }
+  // Use only with literals known at compile time:
+  var defaultAPI = MustParseURL("https://api.example.com")
+  ```
+- `default:` case of an exhaustive sealed-interface switch — see `type-patterns.md`.
+
+The `revive` linter rule `error-return` will flag suspect panic sites; treat them as bugs.
+
+---
+
+## `defer` for resources — the only safe pattern
+
+```go
+func writeReport(path string) (err error) {
+    f, err := os.Create(path)
+    if err != nil {
+        return fmt.Errorf("create %s: %w", path, err)
+    }
+    defer func() {
+        if cerr := f.Close(); cerr != nil && err == nil {
+            err = fmt.Errorf("close %s: %w", path, cerr)
+        }
+    }()
+
+    if _, err := f.Write(data); err != nil {
+        return fmt.Errorf("write %s: %w", path, err)
+    }
+    return nil
+}
+```
+
+Key points:
+
+- `defer f.Close()` immediately after `os.Create` — never further down.
+- Named return `(err error)` so the deferred close can mutate it on close failure.
+- `bodyclose` linter catches missed `defer resp.Body.Close()` for HTTP responses.
+- `sqlclosecheck` linter catches missed `defer rows.Close()` for SQL.
+
+### `errors.Join` for multi-stage cleanup
+
+```go
+func process(path string) (err error) {
+    f, err := os.Open(path)
+    if err != nil { return err }
+    defer func() {
+        err = errors.Join(err, f.Close())
+    }()
+    // ... use f ...
+    return nil
+}
+```
+
+When both the main operation AND `Close` can fail, `errors.Join` reports both without dropping either.
+
+---
+
+## HTTP error responses — a single funnel
+
+Build one helper, route all handler errors through it:
+
+```go
+package httperr
+
+type APIError struct {
+    Status  int    `json:"-"`
+    Code    string `json:"code"`
+    Message string `json:"message"`
+}
+
+func (e *APIError) Error() string { return e.Code + ": " + e.Message }
+
+var (
+    NotFound       = &APIError{Status: 404, Code: "not_found", Message: "resource not found"}
+    Unauthorized   = &APIError{Status: 401, Code: "unauthorized", Message: "unauthorized"}
+    BadRequest     = &APIError{Status: 400, Code: "bad_request", Message: "bad request"}
+    Internal       = &APIError{Status: 500, Code: "internal", Message: "internal error"}
+)
+
+// Wrap a domain error into an API error.
+func From(err error) *APIError {
+    if err == nil { return nil }
+
+    var apiErr *APIError
+    if errors.As(err, &apiErr) { return apiErr }
+
+    switch {
+    case errors.Is(err, domain.ErrInvalidEmail),
+         errors.Is(err, domain.ErrInvalidUsername):
+        return &APIError{Status: 400, Code: "validation", Message: err.Error()}
+    case errors.Is(err, ErrNotFound):
+        return NotFound
+    case errors.Is(err, ErrUnauthorized):
+        return Unauthorized
+    default:
+        // unknown — log full chain, return generic
+        slog.Error("unmapped error", slog.Any("err", err))
+        return Internal
+    }
+}
+
+func Write(c *gin.Context, err error) {
+    apiErr := From(err)
+    c.JSON(apiErr.Status, apiErr)
+}
+```
+
+Handlers become trivial:
+
+```go
+func (h *Handler) Create(c *gin.Context) {
+    user, err := h.svc.Create(c.Request.Context(), req)
+    if err != nil {
+        httperr.Write(c, err)
+        return
+    }
+    c.JSON(201, user)
+}
+```
+
+---
+
+## errgroup — error propagation across goroutines
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func fetchAll(ctx context.Context, urls []string) ([][]byte, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(8)  // concurrency cap
+
+    results := make([][]byte, len(urls))
+    for i, u := range urls {
+        g.Go(func() error {
+            body, err := fetch(ctx, u)
+            if err != nil {
+                return fmt.Errorf("fetch %s: %w", u, err)
+            }
+            results[i] = body
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return results, nil
+}
+```
+
+- `errgroup.WithContext` cancels remaining tasks on first error.
+- `SetLimit` bounds concurrency.
+- First non-nil error is returned; others are discarded — by design.
+
+See `concurrency.md` for the full pattern.
+
+---
+
+## Logging errors — structured, once
+
+```go
+slog.ErrorContext(ctx, "save user failed",
+    slog.String("user_id", string(id)),
+    slog.Any("err", err),   // %w chain is fully rendered
+)
+```
+
+**Log once, at the outermost frame.** Logging at every wrap site produces five log lines for one error.
+
+The `sloglint` linter enforces `slog.Any("err", err)` over `slog.String("err", err.Error())` — the former preserves the chain when handlers walk the value.
+
+---
+
+## Antipatterns
+
+| Bad | Why | Good |
+|---|---|---|
+| `_ = err` | Silent ignore | Handle, log, or wrap |
+| `if err != nil { return err }` chained 10 deep without wrap | No path info | Add one fact per layer: `fmt.Errorf("step: %w", err)` |
+| `panic(err)` in HTTP handlers | Loses error chain, hits gin Recovery | `httperr.Write(c, err)` |
+| `err.Error() == "some string"` | Brittle, breaks on wrap | Define a sentinel, use `errors.Is` |
+| `if err == sql.ErrNoRows` | Breaks under wrap | `errors.Is(err, sql.ErrNoRows)` |
+| `catch-all log.Fatal(err)` in library code | Crashes the caller's process | Return error, let main decide |
+| Returning a typed nil pointer wrapped in error interface | Classic "nil != nil" bug | Return explicit `nil` for the error |
+
+The last bug deserves its own example:
+
+```go
+// BUG — returns a non-nil error interface containing a nil concrete type
+func bad() error {
+    var e *MyError = nil
+    return e  // interface wraps nil pointer; errors == nil is FALSE
+}
+
+// Caller
+if err := bad(); err != nil {
+    // ← entered, but err.(*MyError) is nil — surprise panic
+}
+```
+
+Fix: return explicit `nil`, not a typed nil. The `nilnil` linter catches this in `(T, error)` returns.
+
+---
+
+## Sources
+
+- Go blog "Working with Errors in Go 1.13+": https://go.dev/blog/go1.13-errors
+- `errors.Join` (Go 1.20+): https://pkg.go.dev/errors#Join
+- errorlint: https://github.com/polyfloyd/go-errorlint
+- nilaway nil-interface check: https://github.com/uber-go/nilaway

package/marketplace/plugins/litcodex/skills/lit-code/references/go/golangci-strict.md

@@ -0,0 +1,236 @@
+# Strict `.golangci.yml` (golangci-lint v2)
+
+The single source of truth for "is this Go code acceptable". Drop this in unmodified. **Every linter below is enabled deliberately — read the rationale before disabling one.**
+
+`golangci-lint` v2 changed config schema (top-level `version: "2"`). All v1 configs are incompatible. The block below is v2.
+
+## `.golangci.yml`
+
+```yaml
+version: "2"
+
+run:
+  timeout: 5m
+  tests: true
+  modules-download-mode: readonly
+
+linters:
+  default: none
+  enable:
+    # ── Correctness — bug catchers ───────────────────────────────
+    - govet              # stdlib vet, includes shadow, fieldalignment, nilness
+    - staticcheck        # SA1*-SA9* — the de facto Go correctness linter
+    - errcheck           # unhandled errors. ZERO tolerance.
+    - errorlint          # %w wrapping, errors.As vs type-assertion, errors.Is vs ==
+    - nilerr             # `return nil` after `err != nil` — classic bug
+    - nilnil             # returning `(nil, nil)` from a (*T, error) function
+    - bodyclose          # http.Response.Body not closed
+    - rowserrcheck       # sql.Rows.Err() not checked
+    - sqlclosecheck      # sql.Rows / sql.Stmt not closed
+    - contextcheck       # functions taking context.Context don't get context.Background()
+    - fatcontext         # context.WithValue() in a loop — leaks
+    - copyloopvar        # Go 1.22 loop-var capture — should now use the new semantics
+    - intrange           # use `for i := range N` (Go 1.22+) instead of `for i := 0; i < N; i++`
+    - usetesting         # use t.TempDir/t.Setenv over os.* in tests
+    - testifylint        # require vs assert correctness, ObjectsAreEqual misuse
+
+    # ── Style / readability — kept narrow to avoid bikeshedding ─
+    - gofumpt            # stricter gofmt
+    - goimports          # import grouping + local prefix
+    - whitespace         # leading/trailing whitespace
+    - misspell           # typos in comments and strings
+    - unconvert          # redundant type conversions
+    - unparam            # unused function parameters
+    - ineffassign        # ineffective assignments
+    - dupword            # duplicate words ("the the")
+
+    # ── Architecture — file size, complexity, dead code ─────────
+    - gocognit           # cognitive complexity per function (threshold 25)
+    - gocyclo            # cyclomatic complexity per function (threshold 15)
+    - funlen             # function length (90 lines, 60 statements)
+    - lll                # line length 120
+    - nestif             # excessive nesting depth (>4)
+    - dupl               # duplicate code blocks
+    - revive             # extensible replacement for golint; selected rules below
+    - unused             # unused vars/funcs/types
+
+    # ── Exhaustiveness — Go's weakest spot ──────────────────────
+    - exhaustive         # type switch and enum-like const groups completeness
+
+    # ── Security ────────────────────────────────────────────────
+    - gosec              # CWE-aware security scanner
+
+    # ── Logging ─────────────────────────────────────────────────
+    - sloglint           # slog attr style + no slog.Any(); enforce structured logs
+
+    # ── Performance ─────────────────────────────────────────────
+    - perfsprint         # fmt.Sprintf where strconv suffices
+    - prealloc           # slice prealloc when length is known
+    - makezero           # make([]T, n) with non-zero n then append (the classic bug)
+
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+    check-blank: true     # `_ = err` is a violation
+
+  govet:
+    enable-all: true
+    settings:
+      shadow:
+        strict: true
+      fieldalignment:
+        # On by default; this catches struct layouts wasting memory.
+        # Disable per-file with //nolint:fieldalignment ONLY for boundary types
+        # whose JSON tag order matters for OpenAPI doc stability.
+
+  errorlint:
+    errorf: true          # %w mandatory for wrapping
+    asserts: true         # errors.As over type-assertion on `error`
+    comparison: true      # errors.Is over ==
+
+  gocognit:
+    min-complexity: 25
+
+  gocyclo:
+    min-complexity: 15
+
+  funlen:
+    lines: 90
+    statements: 60
+    ignore-comments: true
+
+  lll:
+    line-length: 120
+    tab-width: 4
+
+  nestif:
+    min-complexity: 4
+
+  exhaustive:
+    default-signifies-exhaustive: false
+    check:
+      - switch
+      - map
+
+  gosec:
+    excludes:
+      - G104        # handled by errcheck/errorlint
+      - G304        # file path provided as input — too noisy for CLIs
+
+  sloglint:
+    no-mixed-args: true       # all attr or all key-value, never mixed
+    kv-only: false
+    attr-only: true           # force slog.String(...) form
+    no-global: all            # disallow slog.Info; force a logger receiver
+    context: scope            # require *Context variants where ctx is in scope
+    static-msg: true          # msg must be a string literal (not fmt.Sprintf)
+    no-raw-keys: true         # use slog.String("key", ...) not raw "key", "val"
+    key-naming-case: snake
+
+  testifylint:
+    enable-all: true
+    disable:
+      - require-error          # We DO use assert.Error in table-driven loops
+
+  revive:
+    severity: warning
+    rules:
+      - name: var-naming
+      - name: package-comments
+      - name: exported
+      - name: error-return
+      - name: error-naming
+      - name: errorf            # use fmt.Errorf instead of errors.New(fmt.Sprintf)
+      - name: if-return
+      - name: indent-error-flow
+      - name: range-val-in-closure
+      - name: redefines-builtin-id
+      - name: superfluous-else
+      - name: unhandled-error
+        arguments:
+          - "fmt.Print.*"
+          - "fmt.Fprint.*"
+
+  perfsprint:
+    integer-format: true
+    error-format: true
+    bool-format: true
+    string-format: true
+
+  goimports:
+    local-prefixes:
+      - github.com/your-org
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  exclude-rules:
+    # Tests get a longer leash on funlen + lll
+    - path: _test\.go
+      linters:
+        - funlen
+        - lll
+        - dupl
+        - gosec
+    # Generated code never lints
+    - path: \.pb\.go$
+      linters: [all]
+    - path: \.connect\.go$
+      linters: [all]
+    - path: ^.*sqlc/.*\.sql\.go$
+      linters: [all]
+
+formatters:
+  enable:
+    - gofumpt
+    - goimports
+```
+
+## Per-linter rationale (why each is on)
+
+| Linter | What it catches | Why no compromise |
+|---|---|---|
+| `errcheck` (incl. `check-blank: true`) | `_ = err`, ignored errors from `Close()`, `Write()`, `json.Marshal()` | Silent error ignore is the #1 Go bug class. Banning `_ = err` forces a decision at every site. |
+| `errorlint` | `err == io.EOF` instead of `errors.Is(err, io.EOF)`; missing `%w` in `fmt.Errorf` | Once you wrap in middleware, `==` checks silently break. `errors.Is/As` is the only safe form. |
+| `nilerr` / `nilnil` | `return nil` after `err != nil`; `return nil, nil` from `(*T, error)` | Classic AI-generated bugs. Linter catches them mechanically. |
+| `bodyclose` | `defer resp.Body.Close()` missed | Single most common Go memory leak. |
+| `contextcheck` | `ctx := context.Background()` inside a function that received `ctx` | Breaks cancellation propagation — the entire reason ctx exists. |
+| `exhaustive` | `switch x.(type)` missing a sealed-interface variant | **Go's weakest type-system spot.** This linter is the closest thing to compiler-enforced exhaustiveness. |
+| `sloglint` | `slog.Info(...)` (global), mixed `Any`/typed attrs | Without this, structured logging silently degrades into string concatenation. |
+| `govet/shadow` strict | `err := ... ; if ... { err := ...; ... }` shadowing | Hides the real error from outer scope — extremely common. |
+| `govet/fieldalignment` | Struct field order wasting memory | Cheap correctness signal. Disable per-file when JSON tag order matters for OpenAPI. |
+| `copyloopvar` + `intrange` | Pre-1.22 loop-var capture and old `for i := 0; i < N; i++` | The language modernized; the lint enforces it. |
+| `usetesting` | `os.Setenv` / `os.Mkdir` in tests instead of `t.Setenv` / `t.TempDir` | Avoids test isolation bugs. |
+| `gocognit` / `gocyclo` / `funlen` | Functions exceeding cognitive thresholds | Direct architectural signal — same purpose as the 250 LOC ceiling, at function granularity. |
+| `gosec` | CWE patterns — SQL injection, weak crypto, path traversal | Production must pass this. |
+| `testifylint` | `assert.Equal` where `require.Equal` was meant; `ObjectsAreEqual` misuse | Subtle test-correctness bugs. |
+| `perfsprint` | `fmt.Sprintf("%d", n)` instead of `strconv.Itoa(n)` | 5–10x faster in tight loops, lints catch the lazy form. |
+
+## `nolint` policy
+
+`//nolint:linter1,linter2 // <reason>` is permitted with **two hard rules**:
+
+1. **One linter at a time per directive.** No `//nolint:all`. No omitting the linter name.
+2. **A reason after `//` is mandatory.** "Generated code", "false positive — protobuf imports", "OpenAPI field order" are acceptable. "Ignore" is not.
+
+The skill auto-rejects `//nolint` without a reason. So does `revive` if you enable its `nolint` rule.
+
+## CI gate
+
+```bash
+gofumpt -l . | (! grep .)                          # format
+golangci-lint run --timeout 5m ./...                # everything above
+go vet -vettool=$(which fieldalignment) ./...       # extra check (also in govet)
+nilaway ./...                                       # nil-deref static analysis
+go test -race -shuffle=on -count=1 ./...            # races + ordering
+```
+
+Any non-zero exit = the change does not ship.
+
+## Sources
+
+- golangci-lint v2 docs: https://golangci-lint.run/docs/configuration/
+- staticcheck rules: https://staticcheck.dev/docs/checks
+- sloglint: https://github.com/go-simpler/sloglint
+- exhaustive: https://github.com/nishanths/exhaustive
+- nilaway: https://github.com/uber-go/nilaway