@coralai/sps-cli 0.42.0 → 0.43.0

package/skills/golang/references/idioms.md

@@ -0,0 +1,285 @@
+# Go — Idioms
+
+Package layout, naming, zero values, struct embedding, slices.
+
+## Package layout
+
+```
+myapp/
+├── go.mod
+├── cmd/
+│   └── myapp/
+│       └── main.go          # only package main; minimal
+├── internal/                # not importable from outside
+│   ├── user/
+│   │   ├── user.go
+│   │   ├── service.go
+│   │   └── service_test.go
+│   └── http/
+│       └── handler.go
+├── pkg/                     # public, importable (rare for apps)
+└── api/                     # protobufs, openapi
+```
+
+Rules:
+- **`internal/`** forbids import from other modules — use it generously.
+- **`pkg/`** is for libraries you intend to publish. Most apps don't need it.
+- **No `util/`, `common/`, `helpers/`.** Name packages by what they provide: `auth`, `billing`, `httpx`.
+
+## Package names
+
+Lowercase, short, singular, no underscores, no mixed case.
+
+```
+✅ auth, billing, httpx, db, user
+❌ auth_package, userService, UTILS, libCommon
+```
+
+Import name = package name. If the directory name differs, aliasing breaks grep. Keep them aligned.
+
+## Exported vs. unexported
+
+Capital letter = exported. Lowercase = package-private.
+
+```go
+type User struct {          // exported
+    ID    string             // exported field
+    email string             // unexported
+}
+
+func (u *User) Email() string { return u.email }
+```
+
+Don't expose fields if an accessor keeps an invariant. Don't add accessors for pure data types.
+
+## Zero values are usable
+
+Design types so the zero value is safe and meaningful.
+
+```go
+var m sync.Mutex        // ready to use
+var b bytes.Buffer      // ready to use
+
+type Counter struct {   // design for zero-value usability
+    n int
+}
+func (c *Counter) Inc() { c.n++ }
+```
+
+Avoid "must call New()" types. If construction requires validation, make `New` return an error and keep the exported type private if needed.
+
+## Struct literals — use field names
+
+```go
+// ❌
+u := User{"u1", "a@x.com", true}
+
+// ✅
+u := User{
+    ID:    "u1",
+    Email: "a@x.com",
+    Active: true,
+}
+```
+
+Positional literals break silently on field reorders or additions.
+
+## Composition over inheritance — embedding
+
+```go
+type Logger struct { /* ... */ }
+func (l *Logger) Log(msg string) { /* ... */ }
+
+type Service struct {
+    *Logger                         // embedded; Service.Log is promoted
+    db *sql.DB
+}
+```
+
+Good for "is-a" composition and interface satisfaction. Don't use embedding to shortcut field access across unrelated types — that's confusion dressed as reuse.
+
+## Interfaces — small, at the call site
+
+```go
+// ✅ in the caller's package
+package service
+
+type userRepo interface {
+    Find(ctx context.Context, id string) (*User, error)
+}
+
+type Service struct {
+    repo userRepo
+}
+```
+
+The *io.Reader* lesson: one-method interfaces are the norm. `Stringer`, `io.Reader`, `io.Closer`, `error` — all one method.
+
+## Accept interfaces, return structs
+
+```go
+// ✅
+func NewService(r Reader) *Service { ... }     // accepts an interface
+func (s *Service) Get() (*User, error) { ... } // returns a concrete type
+
+// ❌
+func NewService(r *os.File) ...               // over-constrained
+func (s *Service) Get() (fmt.Stringer, error) // under-specified return
+```
+
+The caller decides what abstraction they want; you shouldn't force one on them.
+
+## Slices — the common traps
+
+### Share backing array
+
+```go
+a := []int{1, 2, 3, 4}
+b := a[:2]           // [1 2]; shares backing with a
+b = append(b, 99)    // may overwrite a[2]
+```
+
+When you need independent slices, copy:
+
+```go
+b := append([]int(nil), a[:2]...)     // new backing array
+```
+
+### Preallocate capacity
+
+```go
+// ✅
+out := make([]T, 0, len(xs))
+for _, x := range xs { out = append(out, f(x)) }
+
+// ❌ grows repeatedly, each growth may realloc + copy
+var out []T
+for _, x := range xs { out = append(out, f(x)) }
+```
+
+### Nil slice vs. empty slice
+
+Both have length 0. Both work with `range`, `len`, `append`. The difference shows up in JSON (`null` vs `[]`) and reflection-based equality. For public APIs, return `[]T{}` (empty) unless nil is semantically meaningful.
+
+## Maps — iteration order is randomized
+
+Never rely on map iteration order. Sort keys first when order matters.
+
+```go
+keys := make([]string, 0, len(m))
+for k := range m { keys = append(keys, k) }
+sort.Strings(keys)
+for _, k := range keys { fmt.Println(k, m[k]) }
+```
+
+## `for range` pitfalls
+
+Until Go 1.22, the loop variable was shared — a common source of goroutine bugs:
+
+```go
+// Go < 1.22 — BUG
+for _, x := range xs {
+    go func() { use(x) }()          // all goroutines see the last x
+}
+
+// Go < 1.22 — FIX
+for _, x := range xs {
+    x := x                           // shadow into a new variable
+    go func() { use(x) }()
+}
+
+// Go 1.22+ — per-iteration scope; works correctly without shadowing
+```
+
+Check your `go.mod`'s `go` version.
+
+## `defer` — cleanup, not logic
+
+```go
+f, err := os.Open(path)
+if err != nil { return err }
+defer f.Close()             // ✅ cleanup
+```
+
+Rules:
+- `defer` runs in reverse order.
+- `defer` captures args at the `defer` site, not at call time.
+- Don't defer in a hot loop — each `defer` costs an allocation; move cleanup into a helper.
+- Check the error of deferred `Close` on writes (`defer f.Close()` hides the last flush error).
+
+```go
+defer func() {
+    if cerr := f.Close(); cerr != nil && err == nil {
+        err = cerr
+    }
+}()
+```
+
+## Constants & iota
+
+```go
+const (
+    StatusPending = "pending"
+    StatusActive  = "active"
+)
+
+type Day int
+const (
+    Sun Day = iota
+    Mon
+    Tue
+)
+```
+
+Prefer typed constants (`type Day int`) for enums so compile catches wrong-type assignment.
+
+## Strings and bytes
+
+`string` is immutable bytes. `[]byte` is mutable. Convert deliberately — conversions copy.
+
+```go
+b := []byte(s)           // allocates
+s := string(b)           // allocates
+
+// hot path: avoid repeated conversions; keep the type you need
+```
+
+`strings.Builder` for concatenation in a loop — `+` reallocates every time.
+
+## Formatting — `gofmt` / `goimports` is the law
+
+No team style debates. `goimports` groups and sorts imports:
+
+```go
+import (
+    "context"
+    "fmt"
+
+    "github.com/example/mod"
+
+    "myapp/internal/user"
+)
+```
+
+Standard lib → third-party → internal, separated by blank lines.
+
+## Receiver types — pointer vs. value
+
+Rules of thumb:
+- If the method modifies the receiver → pointer.
+- If the struct contains a `sync.Mutex` or similar → pointer (never copy a lock).
+- Large struct (say > 64 bytes) → pointer (avoid copy).
+- Otherwise, either works. Be consistent across a type's methods — don't mix.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Getters/setters for plain data | Exported fields; only add methods when behaviour is needed |
+| `init()` doing work | Do it explicitly in `main` |
+| Variable shadowing across scopes | `go vet` catches the bad cases; pay attention |
+| Using `interface{}` / `any` everywhere | Reach for concrete types first |
+| Long files (>500 lines) | Split by responsibility, not by arbitrary size |
+| `len(s) > 0` to check non-empty | `s != ""` is the idiom |
+| Custom `String()` with side effects | `fmt` calls it at any time; must be pure |
+| "Manager", "Util", "Helper" names | Name by what the type actually is |

package/skills/golang/references/testing.md

@@ -0,0 +1,238 @@
+# Go — Testing
+
+`testing` package, table-driven tests, subtests, benchmarks, fuzzing. For general TDD, see `coding-standards/references/tdd.md`.
+
+## Conventions
+
+- File: `*_test.go` next to the code it tests.
+- Package: same as the code (`package user`) for white-box; `package user_test` for black-box (public API only).
+- Test function: `func TestXxx(t *testing.T)`.
+- Run: `go test ./...`
+
+```go
+// user_test.go
+package user
+
+import "testing"
+
+func TestNormalizeEmail(t *testing.T) {
+    got := Normalize("  A@X.COM ")
+    want := "a@x.com"
+    if got != want {
+        t.Errorf("Normalize: got %q, want %q", got, want)
+    }
+}
+```
+
+`t.Errorf` logs and continues. `t.Fatalf` stops the test.
+
+## Table-driven tests
+
+The idiomatic way.
+
+```go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name    string
+        a, b    int
+        want    int
+    }{
+        {"two positives", 2, 3, 5},
+        {"zero", 0, 0, 0},
+        {"negative", -1, 1, 0},
+    }
+    for _, tt := range tests {
+        tt := tt                          // shadow for Go < 1.22
+        t.Run(tt.name, func(t *testing.T) {
+            if got := Add(tt.a, tt.b); got != tt.want {
+                t.Errorf("got %d, want %d", got, tt.want)
+            }
+        })
+    }
+}
+```
+
+Benefits: `t.Run` gives each case its own name for `-run` filtering and parallel runs.
+
+## `t.Parallel()`
+
+Mark tests that can run in parallel.
+
+```go
+func TestX(t *testing.T) {
+    t.Parallel()
+    ...
+}
+```
+
+Rules:
+- Don't mutate package globals or filesystem fixtures.
+- Subtests inherit parallelism; put `t.Parallel()` in each `t.Run`.
+- If a test is slow or has setup cost, parallel compounds: N tests × 10× speedup = big wins.
+
+## Test helpers — mark with `t.Helper()`
+
+```go
+func requireUser(t *testing.T, got, want *User) {
+    t.Helper()                         // errors report the caller's line
+    if got.ID != want.ID { t.Errorf("id: got %s want %s", got.ID, want.ID) }
+}
+```
+
+Without `t.Helper()`, error line points inside the helper instead of the test body.
+
+## `testify` — when assertions get verbose
+
+The standard lib is fine for most cases. `testify/require` helps when you have many assertions.
+
+```go
+import "github.com/stretchr/testify/require"
+
+func TestUser(t *testing.T) {
+    u, err := Get(id)
+    require.NoError(t, err)
+    require.NotNil(t, u)
+    require.Equal(t, "A", u.Name)
+}
+```
+
+Use `require` (stops on fail) vs `assert` (continues). `require` avoids nil-deref panics in the next line after a failure.
+
+Don't reach for `testify/mock` by default — prefer real fakes for repos, test HTTP servers, etc.
+
+## Fakes over mocks
+
+```go
+// ✅ fake repo — behaves like the real one, in memory
+type fakeUserRepo struct { users map[string]*User }
+func newFakeUserRepo() *fakeUserRepo { return &fakeUserRepo{users: map[string]*User{}} }
+func (r *fakeUserRepo) Find(_ context.Context, id string) (*User, error) { return r.users[id], nil }
+func (r *fakeUserRepo) Save(_ context.Context, u *User) error { r.users[u.ID] = u; return nil }
+```
+
+For HTTP dependencies, `httptest.NewServer` gives you a real server at a real port.
+
+```go
+srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+    fmt.Fprint(w, `{"id":"u_1"}`)
+}))
+defer srv.Close()
+
+client := NewClient(srv.URL)
+u, _ := client.Get(ctx, "u_1")
+```
+
+## Golden files — for large expected output
+
+```go
+var update = flag.Bool("update", false, "update golden files")
+
+func TestRender(t *testing.T) {
+    got := Render(input)
+    golden := filepath.Join("testdata", "render.golden")
+    if *update {
+        os.WriteFile(golden, got, 0644)
+    }
+    want, _ := os.ReadFile(golden)
+    if !bytes.Equal(got, want) {
+        t.Errorf("render diff; run with -update to regenerate")
+    }
+}
+```
+
+Run `go test -update` to regenerate after deliberate changes. Review the diff like any other.
+
+## Benchmarks
+
+```go
+func BenchmarkAdd(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        Add(2, 3)
+    }
+}
+```
+
+Run: `go test -bench=. -benchmem ./...`.
+
+Use `b.ReportAllocs()` or `-benchmem` to track allocations; ns/op matters, allocs/op often matters more.
+
+Always benchmark the thing you want to measure. Pre-compute inputs outside the timed loop:
+
+```go
+func BenchmarkHash(b *testing.B) {
+    data := make([]byte, 1024)
+    rand.Read(data)
+    b.ResetTimer()                     // reset after setup
+    for i := 0; i < b.N; i++ {
+        _ = sha256.Sum256(data)
+    }
+}
+```
+
+## Fuzzing (Go 1.18+)
+
+For parsers, validators, anything with a big input space.
+
+```go
+func FuzzParseURL(f *testing.F) {
+    f.Add("http://x.com")
+    f.Fuzz(func(t *testing.T, s string) {
+        u, err := Parse(s)
+        if err == nil && u.String() != s {
+            t.Errorf("roundtrip failed: %q != %q", u.String(), s)
+        }
+    })
+}
+```
+
+Run: `go test -fuzz=FuzzParseURL -fuzztime=30s`. Failing inputs are saved to `testdata/fuzz/<name>/` — commit them to prevent regressions.
+
+## Integration tests
+
+Build tag or separate directory to keep them out of the default run.
+
+```go
+//go:build integration
+package integration_test
+
+func TestDBReal(t *testing.T) { ... }
+```
+
+Run: `go test -tags=integration ./...`.
+
+Or: separate package under `internal/integration/` and a Makefile target.
+
+## Race detector in CI
+
+Always. Always. Always.
+
+```
+go test -race ./...
+```
+
+## Coverage
+
+```
+go test -cover ./...
+go test -coverprofile=c.out ./... && go tool cover -html=c.out
+```
+
+Set a floor in CI:
+
+```
+go test -coverprofile=c.out ./...
+go tool cover -func=c.out | grep total: | awk '{if ($3+0 < 80.0) exit 1}'
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| One `Test*` per file instead of one `TestMain` | Table-driven tests fold the variants |
+| `fmt.Println` in tests for debugging | `t.Logf` — only shows on failure |
+| `time.Sleep` to wait for async | Use channels, `WaitGroup`, or deterministic test clock |
+| Shared package-level state between tests | Reset in each test, or don't use globals |
+| `testify/mock` boilerplate for everything | Hand-write a fake; less code, clearer intent |
+| Snapshot tests for time / UUID output | Inject a clock / uuid generator; test against deterministic output |
+| Benchmarks that don't `ResetTimer` after setup | You're benchmarking setup, not the function |
+| Disabling a failing test to unblock CI | Fix or delete |

package/skills/java/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: java
+description: Java language skill — modern idioms (17+/21 LTS), records, streams, concurrency, testing. Pair with `backend` / `mobile` end skills and `coding-standards` for cross-language principles.
+origin: original
+---
+
+# Java
+
+Modern Java (17 LTS / 21 LTS+). Records, sealed types, switch patterns, virtual threads. **Language-focused**.
+
+## When to load
+
+- Project primary language is Java 17+ (LTS) or 21+ (virtual threads)
+- Reviewing Java code
+- Backend services (Spring Boot, Quarkus, Helidon, Micronaut)
+- Android (where Kotlin isn't used)
+- JVM interop with Kotlin / Scala
+
+## Core principles
+
+1. **Records for data.** Replace `@Data` Lombok classes and hand-written POJOs.
+2. **Sealed types + pattern switch for sum types.** Replace visitor pattern and `instanceof` chains.
+3. **`var` for locals only.** Never in method signatures / fields.
+4. **`Optional<T>` for return values, never for fields or parameters.**
+5. **Virtual threads (21+) for I/O-bound concurrency.** Replace manual thread pools and reactive chains where they exist only for thread efficiency.
+6. **Unmodifiable collections by default.** `List.of(...)`, `Map.of(...)`, `Collectors.toUnmodifiableList()`.
+7. **Checked exceptions for recoverable failures in libraries; runtime exceptions for programmer errors.** Don't catch-and-rethrow just to convert one kind.
+8. **`NullPointerException` is a bug.** Don't normalize it with defensive `null` checks everywhere; design so the type system documents nullability.
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/idioms.md`](references/idioms.md) | Records, sealed types, streams, `Optional`, collections, `var` |
+| [`references/concurrency.md`](references/concurrency.md) | Virtual threads, `CompletableFuture`, `ExecutorService`, structured concurrency (preview) |
+| [`references/testing.md`](references/testing.md) | JUnit 5, AssertJ, Mockito, Testcontainers |
+
+## Forbidden patterns (auto-reject)
+
+- Raw types (`List` without `<T>`)
+- `Vector`, `Hashtable`, `Stack` (legacy, synchronized) — use modern collections
+- `new Integer(...)` etc. — use `Integer.valueOf(...)`
+- `null` return where `Optional<T>` would be expressive
+- Catching `Exception` / `Throwable` broadly without re-throw
+- `String.format` for log messages — use parameterized SLF4J (`logger.info("x={}", x)`)
+- Mutable static fields for business data
+- `Thread.sleep` in request handlers
+- `checkedException.wrap(RuntimeException)` without cause chain
+- Anonymous inner classes where a lambda works
+- `Date` / `Calendar` / `SimpleDateFormat` — use `java.time.*` (since Java 8!)