aigroup-workflow 2.1.1 → 2.2.0

package/skills/go-rust-cpp/golang-pro/references/testing.md

@@ -0,0 +1,451 @@
+# Testing and Benchmarking
+
+## Table-Driven Tests
+
+```go
+package math
+
+import "testing"
+
+func Add(a, b int) int {
+    return a + b
+}
+
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 2, 3, 5},
+        {"negative numbers", -2, -3, -5},
+        {"mixed signs", -2, 3, 1},
+        {"zeros", 0, 0, 0},
+        {"large numbers", 1000000, 2000000, 3000000},
+    }
+
+    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)
+            }
+        })
+    }
+}
+```
+
+## Subtests and Parallel Execution
+
+```go
+func TestParallel(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+        want  string
+    }{
+        {"lowercase", "hello", "HELLO"},
+        {"uppercase", "WORLD", "WORLD"},
+        {"mixed", "HeLLo", "HELLO"},
+    }
+
+    for _, tt := range tests {
+        tt := tt // Capture range variable for parallel tests
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel() // Run subtests in parallel
+
+            result := strings.ToUpper(tt.input)
+            if result != tt.want {
+                t.Errorf("got %q, want %q", result, tt.want)
+            }
+        })
+    }
+}
+```
+
+## Test Helpers and Setup/Teardown
+
+```go
+func TestWithSetup(t *testing.T) {
+    // Setup
+    db := setupTestDB(t)
+    defer cleanupTestDB(t, db)
+
+    tests := []struct {
+        name string
+        user User
+    }{
+        {"valid user", User{Name: "John", Email: "john@example.com"}},
+        {"empty name", User{Name: "", Email: "test@example.com"}},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := db.SaveUser(tt.user)
+            if err != nil {
+                t.Fatalf("SaveUser failed: %v", err)
+            }
+        })
+    }
+}
+
+// Helper function (doesn't show in stack trace)
+func setupTestDB(t *testing.T) *DB {
+    t.Helper()
+
+    db, err := NewDB(":memory:")
+    if err != nil {
+        t.Fatalf("failed to create test DB: %v", err)
+    }
+    return db
+}
+
+func cleanupTestDB(t *testing.T, db *DB) {
+    t.Helper()
+
+    if err := db.Close(); err != nil {
+        t.Errorf("failed to close DB: %v", err)
+    }
+}
+```
+
+## Mocking with Interfaces
+
+```go
+// Interface to mock
+type EmailSender interface {
+    Send(to, subject, body string) error
+}
+
+// Mock implementation
+type MockEmailSender struct {
+    SentEmails []Email
+    ShouldFail bool
+}
+
+type Email struct {
+    To, Subject, Body string
+}
+
+func (m *MockEmailSender) Send(to, subject, body string) error {
+    if m.ShouldFail {
+        return fmt.Errorf("failed to send email")
+    }
+    m.SentEmails = append(m.SentEmails, Email{to, subject, body})
+    return nil
+}
+
+// Test using mock
+func TestUserService_Register(t *testing.T) {
+    mockSender := &MockEmailSender{}
+    service := NewUserService(mockSender)
+
+    err := service.Register("user@example.com")
+    if err != nil {
+        t.Fatalf("Register failed: %v", err)
+    }
+
+    if len(mockSender.SentEmails) != 1 {
+        t.Errorf("expected 1 email sent, got %d", len(mockSender.SentEmails))
+    }
+
+    email := mockSender.SentEmails[0]
+    if email.To != "user@example.com" {
+        t.Errorf("expected email to user@example.com, got %s", email.To)
+    }
+}
+```
+
+## Benchmarking
+
+```go
+func BenchmarkAdd(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        Add(100, 200)
+    }
+}
+
+// Benchmark with subtests
+func BenchmarkStringOperations(b *testing.B) {
+    benchmarks := []struct {
+        name  string
+        input string
+    }{
+        {"short", "hello"},
+        {"medium", strings.Repeat("hello", 10)},
+        {"long", strings.Repeat("hello", 100)},
+    }
+
+    for _, bm := range benchmarks {
+        b.Run(bm.name, func(b *testing.B) {
+            for i := 0; i < b.N; i++ {
+                _ = strings.ToUpper(bm.input)
+            }
+        })
+    }
+}
+
+// Benchmark with setup
+func BenchmarkMapOperations(b *testing.B) {
+    m := make(map[string]int)
+    for i := 0; i < 1000; i++ {
+        m[fmt.Sprintf("key%d", i)] = i
+    }
+
+    b.ResetTimer() // Don't count setup time
+
+    for i := 0; i < b.N; i++ {
+        _ = m["key500"]
+    }
+}
+
+// Parallel benchmark
+func BenchmarkConcurrentAccess(b *testing.B) {
+    var counter int64
+
+    b.RunParallel(func(pb *testing.PB) {
+        for pb.Next() {
+            atomic.AddInt64(&counter, 1)
+        }
+    })
+}
+
+// Memory allocation benchmark
+func BenchmarkAllocation(b *testing.B) {
+    b.ReportAllocs() // Report allocations
+
+    for i := 0; i < b.N; i++ {
+        s := make([]int, 1000)
+        _ = s
+    }
+}
+```
+
+## Fuzzing (Go 1.18+)
+
+```go
+func FuzzReverse(f *testing.F) {
+    // Seed corpus
+    testcases := []string{"hello", "world", "123", ""}
+    for _, tc := range testcases {
+        f.Add(tc)
+    }
+
+    f.Fuzz(func(t *testing.T, input string) {
+        reversed := Reverse(input)
+        doubleReversed := Reverse(reversed)
+
+        if input != doubleReversed {
+            t.Errorf("Reverse(Reverse(%q)) = %q, want %q", input, doubleReversed, input)
+        }
+    })
+}
+
+// Fuzz with multiple parameters
+func FuzzAdd(f *testing.F) {
+    f.Add(1, 2)
+    f.Add(0, 0)
+    f.Add(-1, 1)
+
+    f.Fuzz(func(t *testing.T, a, b int) {
+        result := Add(a, b)
+
+        // Properties that should always hold
+        if result < a && b >= 0 {
+            t.Errorf("Add(%d, %d) = %d; result should be >= a when b >= 0", a, b, result)
+        }
+    })
+}
+```
+
+## Test Coverage
+
+```go
+// Run tests with coverage:
+// go test -cover
+// go test -coverprofile=coverage.out
+// go tool cover -html=coverage.out
+
+func TestCalculate(t *testing.T) {
+    tests := []struct {
+        name     string
+        input    int
+        expected int
+    }{
+        {"zero", 0, 0},
+        {"positive", 5, 25},
+        {"negative", -3, 9},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Calculate(tt.input)
+            if result != tt.expected {
+                t.Errorf("Calculate(%d) = %d; want %d", tt.input, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+## Race Detector
+
+```go
+// Run with: go test -race
+
+func TestConcurrentAccess(t *testing.T) {
+    var counter int
+    var wg sync.WaitGroup
+
+    // This will fail with -race if not synchronized
+    for i := 0; i < 10; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            counter++ // Data race!
+        }()
+    }
+
+    wg.Wait()
+}
+
+// Fixed version with mutex
+func TestConcurrentAccessSafe(t *testing.T) {
+    var counter int
+    var mu sync.Mutex
+    var wg sync.WaitGroup
+
+    for i := 0; i < 10; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            mu.Lock()
+            counter++
+            mu.Unlock()
+        }()
+    }
+
+    wg.Wait()
+
+    if counter != 10 {
+        t.Errorf("expected 10, got %d", counter)
+    }
+}
+```
+
+## Golden Files
+
+```go
+import (
+    "os"
+    "path/filepath"
+    "testing"
+)
+
+func TestRenderHTML(t *testing.T) {
+    data := Data{Title: "Test", Content: "Hello"}
+    result := RenderHTML(data)
+
+    goldenFile := filepath.Join("testdata", "expected.html")
+
+    if *update {
+        // Update golden file: go test -update
+        os.WriteFile(goldenFile, []byte(result), 0644)
+    }
+
+    expected, err := os.ReadFile(goldenFile)
+    if err != nil {
+        t.Fatalf("failed to read golden file: %v", err)
+    }
+
+    if result != string(expected) {
+        t.Errorf("output doesn't match golden file\ngot:\n%s\nwant:\n%s", result, expected)
+    }
+}
+
+var update = flag.Bool("update", false, "update golden files")
+```
+
+## Integration Tests
+
+```go
+// integration_test.go
+// +build integration
+
+package myapp
+
+import (
+    "testing"
+    "time"
+)
+
+func TestIntegration(t *testing.T) {
+    if testing.Short() {
+        t.Skip("skipping integration test in short mode")
+    }
+
+    // Long-running integration test
+    server := startTestServer(t)
+    defer server.Stop()
+
+    time.Sleep(100 * time.Millisecond) // Wait for server
+
+    client := NewClient(server.URL)
+    resp, err := client.Get("/health")
+    if err != nil {
+        t.Fatalf("health check failed: %v", err)
+    }
+
+    if resp.Status != "ok" {
+        t.Errorf("expected status ok, got %s", resp.Status)
+    }
+}
+
+// Run: go test -tags=integration
+// Run short tests only: go test -short
+```
+
+## Testable Examples
+
+```go
+// Example tests that appear in godoc
+func ExampleAdd() {
+    result := Add(2, 3)
+    fmt.Println(result)
+    // Output: 5
+}
+
+func ExampleAdd_negative() {
+    result := Add(-2, -3)
+    fmt.Println(result)
+    // Output: -5
+}
+
+// Unordered output
+func ExampleKeys() {
+    m := map[string]int{"a": 1, "b": 2, "c": 3}
+    keys := Keys(m)
+    for _, k := range keys {
+        fmt.Println(k)
+    }
+    // Unordered output:
+    // a
+    // b
+    // c
+}
+```
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `go test` | Run tests |
+| `go test -v` | Verbose output |
+| `go test -run TestName` | Run specific test |
+| `go test -bench .` | Run benchmarks |
+| `go test -cover` | Show coverage |
+| `go test -race` | Run race detector |
+| `go test -short` | Skip long tests |
+| `go test -fuzz FuzzName` | Run fuzzing |
+| `go test -cpuprofile cpu.prof` | CPU profiling |
+| `go test -memprofile mem.prof` | Memory profiling |

package/skills/go-rust-cpp/rust-engineer/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: rust-engineer
+description: Writes, reviews, and debugs idiomatic Rust code with memory safety and zero-cost abstractions. Implements ownership patterns, manages lifetimes, designs trait hierarchies, builds async applications with tokio, and structures error handling with Result/Option. Use when building Rust applications, solving ownership or borrowing issues, designing trait-based APIs, implementing async/await concurrency, creating FFI bindings, or optimizing for performance and memory safety. Invoke for Rust, Cargo, ownership, borrowing, lifetimes, async Rust, tokio, zero-cost abstractions, memory safety, systems programming.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: language
+  triggers: Rust, Cargo, ownership, borrowing, lifetimes, async Rust, tokio, zero-cost abstractions, memory safety, systems programming
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: test-master
+---
+
+# Rust Engineer
+
+Senior Rust engineer with deep expertise in Rust 2021 edition, systems programming, memory safety, and zero-cost abstractions. Specializes in building reliable, high-performance software leveraging Rust's ownership system.
+
+## Core Workflow
+
+1. **Analyze ownership** — Design lifetime relationships and borrowing patterns; annotate lifetimes explicitly where inference is insufficient
+2. **Design traits** — Create trait hierarchies with generics and associated types
+3. **Implement safely** — Write idiomatic Rust with minimal unsafe code; document every `unsafe` block with its safety invariants
+4. **Handle errors** — Use `Result`/`Option` with `?` operator and custom error types via `thiserror`
+5. **Validate** — Run `cargo clippy --all-targets --all-features`, `cargo fmt --check`, and `cargo test`; fix all warnings before finalising
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Ownership | `references/ownership.md` | Lifetimes, borrowing, smart pointers, Pin |
+| Traits | `references/traits.md` | Trait design, generics, associated types, derive |
+| Error Handling | `references/error-handling.md` | Result, Option, ?, custom errors, thiserror |
+| Async | `references/async.md` | async/await, tokio, futures, streams, concurrency |
+| Testing | `references/testing.md` | Unit/integration tests, proptest, benchmarks |
+
+## Key Patterns with Examples
+
+### Ownership & Lifetimes
+
+```rust
+// Explicit lifetime annotation — borrow lives as long as the input slice
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+
+// Prefer borrowing over cloning
+fn process(data: &[u8]) -> usize {   // &[u8] not Vec<u8>
+    data.iter().filter(|&&b| b != 0).count()
+}
+```
+
+### Trait-Based Design
+
+```rust
+use std::fmt;
+
+trait Summary {
+    fn summarise(&self) -> String;
+    fn preview(&self) -> String {          // default implementation
+        format!("{}...", &self.summarise()[..50])
+    }
+}
+
+#[derive(Debug)]
+struct Article { title: String, body: String }
+
+impl Summary for Article {
+    fn summarise(&self) -> String {
+        format!("{}: {}", self.title, self.body)
+    }
+}
+```
+
+### Error Handling with `thiserror`
+
+```rust
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum AppError {
+    #[error("I/O error: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("parse error for value `{value}`: {reason}")]
+    Parse { value: String, reason: String },
+}
+
+// ? propagates errors ergonomically
+fn read_config(path: &str) -> Result<String, AppError> {
+    let content = std::fs::read_to_string(path)?;  // Io variant via #[from]
+    Ok(content)
+}
+```
+
+### Async / Await with Tokio
+
+```rust
+use tokio::time::{sleep, Duration};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let result = fetch_data("https://example.com").await?;
+    println!("{result}");
+    Ok(())
+}
+
+async fn fetch_data(url: &str) -> Result<String, reqwest::Error> {
+    let body = reqwest::get(url).await?.text().await?;
+    Ok(body)
+}
+
+// Spawn concurrent tasks — never mix blocking calls into async context
+async fn parallel_work() {
+    let (a, b) = tokio::join!(
+        sleep(Duration::from_millis(100)),
+        sleep(Duration::from_millis(100)),
+    );
+}
+```
+
+### Validation Commands
+
+```bash
+cargo fmt --check                          # style check
+cargo clippy --all-targets --all-features  # lints
+cargo test                                 # unit + integration tests
+cargo test --doc                           # doctests
+cargo bench                                # criterion benchmarks (if present)
+```
+
+## Constraints
+
+### MUST DO
+- Use ownership and borrowing for memory safety
+- Minimize unsafe code (document all unsafe blocks with safety invariants)
+- Use type system for compile-time guarantees
+- Handle all errors explicitly (`Result`/`Option`)
+- Add comprehensive documentation with examples
+- Run `cargo clippy` and fix all warnings
+- Use `cargo fmt` for consistent formatting
+- Write tests including doctests
+
+### MUST NOT DO
+- Use `unwrap()` in production code (prefer `expect()` with messages)
+- Create memory leaks or dangling pointers
+- Use `unsafe` without documenting safety invariants
+- Ignore clippy warnings
+- Mix blocking and async code incorrectly
+- Skip error handling
+- Use `String` when `&str` suffices
+- Clone unnecessarily (use borrowing)
+
+## Output Templates
+
+When implementing Rust features, provide:
+1. Type definitions (structs, enums, traits)
+2. Implementation with proper ownership
+3. Error handling with custom error types
+4. Tests (unit, integration, doctests)
+5. Brief explanation of design decisions
+
+## Knowledge Reference
+
+Rust 2021, Cargo, ownership/borrowing, lifetimes, traits, generics, async/await, tokio, Result/Option, thiserror/anyhow, serde, clippy, rustfmt, cargo-test, criterion benchmarks, MIRI, unsafe Rust