@hivehub/rulebook 1.2.0

package/templates/languages/GO.md

@@ -0,0 +1,645 @@
+<!-- GO:START -->
+# Go Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+gofmt -l .                 # Format check (should be empty)
+golangci-lint run          # Linting
+go vet ./...               # Static analysis
+go test ./... -v -race -coverprofile=coverage.out  # Tests + race detection
+go tool cover -func=coverage.out  # Coverage (95%+ required)
+go build ./...             # Build verification
+
+# Security audit:
+go list -json -m all | nancy sleuth  # Vulnerability scan
+go list -u -m all          # Check outdated deps
+```
+
+## Go Version
+
+**CRITICAL**: Use Go 1.21+ for modern features and performance.
+
+- **Minimum Version**: Go 1.21+
+- **Recommended**: Go 1.22+
+- **Module System**: Go modules enabled
+
+### Formatting
+
+- Use `gofmt` or `goimports` for code formatting
+- Standard Go formatting is non-negotiable
+- Format before committing: `gofmt -w .`
+- CI must check formatting: `gofmt -l . | wc -l` should be 0
+
+### Linting
+
+- Use `golangci-lint` with recommended linters
+- Configuration in `.golangci.yml`
+- Must pass with no issues
+- Enable linters: govet, errcheck, staticcheck, gosimple, unused
+
+Example `.golangci.yml`:
+```yaml
+linters:
+  enable:
+    - govet
+    - errcheck
+    - staticcheck
+    - gosimple
+    - unused
+    - gosec
+    - gocyclo
+    - gofmt
+    - goimports
+    
+linters-settings:
+  gocyclo:
+    min-complexity: 15
+  govet:
+    check-shadowing: true
+    
+issues:
+  exclude-use-default: false
+```
+
+### Testing
+
+- **Framework**: Standard testing package
+- **Location**: `*_test.go` files in same package
+- **Coverage**: Must meet project threshold (default 95%)
+- **Table-Driven Tests**: Use for multiple test cases
+- **Subtests**: Use `t.Run()` for organized tests
+
+Example test structure:
+```go
+package mypackage
+
+import (
+    "testing"
+)
+
+func TestMyFunction(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   string
+        want    string
+        wantErr bool
+    }{
+        {"valid input", "test", "TEST", false},
+        {"empty input", "", "", true},
+    }
+    
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got, err := MyFunction(tt.input)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("MyFunction() error = %v, wantErr %v", err, tt.wantErr)
+                return
+            }
+            if got != tt.want {
+                t.Errorf("MyFunction() = %v, want %v", got, tt.want)
+            }
+        })
+    }
+}
+```
+
+### Test Categories: S2S and Slow Tests
+
+**CRITICAL**: Tests must be categorized based on execution time and dependencies.
+
+#### Test Time Limits
+
+- **Fast Tests**: Must complete in ≤ 10-20 seconds
+- **Slow Tests**: Any test taking > 10-20 seconds must be marked as slow
+- **S2S Tests**: Tests requiring active server/database must be isolated and run on-demand
+
+#### S2S (Server-to-Server) Tests
+
+**Tests that require active servers, databases, or external services must be isolated using build tags.**
+
+**Implementation**:
+
+1. **Use build tags to isolate S2S tests**:
+```go
+// +build s2s
+
+package mypackage
+
+import (
+    "testing"
+    "os"
+)
+
+func TestDatabaseConnection(t *testing.T) {
+    // Requires active database server
+    if os.Getenv("RUN_S2S_TESTS") == "" {
+        t.Skip("S2S tests disabled. Set RUN_S2S_TESTS=1 to enable.")
+    }
+    db := connectToDatabase()
+    // ... test implementation
+}
+
+func TestAPIIntegration(t *testing.T) {
+    // Requires active API server
+    if os.Getenv("RUN_S2S_TESTS") == "" {
+        t.Skip("S2S tests disabled. Set RUN_S2S_TESTS=1 to enable.")
+    }
+    client := createAPIClient()
+    // ... test implementation
+}
+```
+
+2. **Regular tests (without build tag)**:
+```go
+// Regular fast test (always runs)
+package mypackage
+
+import "testing"
+
+func TestLocalComputation(t *testing.T) {
+    // Fast test, no external dependencies
+    result := computeLocally("input")
+    if result != "expected" {
+        t.Errorf("Expected 'expected', got %v", result)
+    }
+}
+```
+
+3. **Run tests**:
+```bash
+# Regular tests (excludes S2S)
+go test ./...
+
+# Include S2S tests (requires active servers)
+RUN_S2S_TESTS=1 go test -tags s2s ./...
+
+# Run only S2S tests
+RUN_S2S_TESTS=1 go test -tags s2s ./... -run TestDatabase
+```
+
+#### Slow Tests
+
+**Tests that take > 10-20 seconds must be marked and run separately.**
+
+**Implementation**:
+
+1. **Use build tags for slow tests**:
+```go
+// +build slow
+
+package mypackage
+
+import (
+    "testing"
+    "time"
+)
+
+func TestHeavyComputation(t *testing.T) {
+    // Takes 30+ seconds
+    start := time.Now()
+    result := processLargeDataset()
+    duration := time.Since(start)
+    
+    if result == nil {
+        t.Error("Expected result, got nil")
+    }
+    t.Logf("Test completed in %v", duration)
+}
+
+func TestLargeFileProcessing(t *testing.T) {
+    // Processes large files, takes > 20 seconds
+    result := processFile("large_file.dat")
+    if !result.Success {
+        t.Error("File processing failed")
+    }
+}
+```
+
+2. **Alternative: Use environment variable**:
+```go
+package mypackage
+
+import (
+    "os"
+    "testing"
+)
+
+func TestHeavyComputation(t *testing.T) {
+    if os.Getenv("RUN_SLOW_TESTS") == "" {
+        t.Skip("Slow tests disabled. Set RUN_SLOW_TESTS=1 to enable.")
+    }
+    // Heavy computation test
+}
+```
+
+3. **Run tests**:
+```bash
+# Regular tests (excludes slow and S2S)
+go test ./...
+
+# Include slow tests
+RUN_SLOW_TESTS=1 go test -tags slow ./...
+
+# Run both S2S and slow tests
+RUN_S2S_TESTS=1 RUN_SLOW_TESTS=1 go test -tags "s2s slow" ./...
+```
+
+4. **Add Makefile targets**:
+```makefile
+.PHONY: test test-s2s test-slow test-all
+
+test:
+	go test ./...
+
+test-s2s:
+	RUN_S2S_TESTS=1 go test -tags s2s ./...
+
+test-slow:
+	RUN_SLOW_TESTS=1 go test -tags slow ./...
+
+test-all:
+	RUN_S2S_TESTS=1 RUN_SLOW_TESTS=1 go test -tags "s2s slow" ./...
+```
+
+5. **Set timeouts in test functions**:
+```go
+func TestWithTimeout(t *testing.T) {
+    done := make(chan bool)
+    go func() {
+        // Long-running test
+        result := heavyOperation()
+        done <- (result != nil)
+    }()
+    
+    select {
+    case success := <-done:
+        if !success {
+            t.Error("Test failed")
+        }
+    case <-time.After(60 * time.Second):
+        t.Fatal("Test timeout after 60 seconds")
+    }
+}
+```
+
+#### Best Practices
+
+- ✅ **Always run fast tests** in CI/CD by default
+- ✅ **Isolate S2S tests** - never run them in standard test suite
+- ✅ **Mark slow tests** - prevent CI/CD timeouts
+- ✅ **Document requirements** - specify which servers/services are needed for S2S tests
+- ✅ **Use build tags** - `// +build s2s` and `// +build slow`
+- ✅ **Use environment variables** - Check `RUN_S2S_TESTS` and `RUN_SLOW_TESTS`
+- ✅ **Set timeouts** - Use `time.After()` or `context.WithTimeout()` for long-running tests
+- ✅ **Skip conditionally** - Use `t.Skip()` when services are unavailable
+- ❌ **Never mix** fast and slow/S2S tests in same test run
+- ❌ **Never require** external services for standard test suite
+- ❌ **Never exceed** 10-20 seconds for regular tests
+
+## Dependency Management
+
+**CRITICAL**: Use Go modules for dependency management.
+
+### go.mod and go.sum
+
+```bash
+# Initialize module
+go mod init github.com/username/project
+
+# Add dependency
+go get github.com/package/name@latest
+
+# Update dependencies
+go get -u ./...
+go mod tidy
+
+# Verify dependencies
+go mod verify
+```
+
+### Dependency Guidelines
+
+1. **Check for latest versions**:
+   - Use Context7 MCP tool if available
+   - Check pkg.go.dev for documentation
+   - Review changelog for breaking changes
+
+2. **Version Selection**:
+   - ✅ Use latest stable versions
+   - ✅ Pin to specific versions for reproducibility
+   - ✅ Keep dependencies updated regularly
+   - ✅ Use `go mod tidy` to remove unused
+   - ❌ Don't use deprecated packages
+   - ❌ Don't vendor unless necessary
+
+## Error Handling
+
+- Always return errors, don't panic
+- Use custom error types with `fmt.Errorf`
+- Wrap errors with context: `fmt.Errorf("operation failed: %w", err)`
+- Check all errors, never ignore
+- Use `errors.Is()` and `errors.As()` for error checking
+
+Example:
+```go
+package mypackage
+
+import (
+    "errors"
+    "fmt"
+)
+
+var (
+    ErrInvalidInput = errors.New("invalid input")
+    ErrNotFound     = errors.New("not found")
+)
+
+func ProcessData(input string) (string, error) {
+    if input == "" {
+        return "", fmt.Errorf("process data: %w", ErrInvalidInput)
+    }
+    
+    result, err := doSomething(input)
+    if err != nil {
+        return "", fmt.Errorf("failed to process: %w", err)
+    }
+    
+    return result, nil
+}
+```
+
+## Documentation
+
+- **Package docs**: Use package comments
+- **Function docs**: Document all exported functions
+- **Examples**: Include in doc comments (will run as tests)
+- **Run godoc**: `go doc -all`
+
+Example:
+```go
+// Package auth provides authentication and authorization utilities.
+//
+// This package implements JWT-based authentication following OAuth 2.0
+// standards. All functions are thread-safe.
+package auth
+
+// Authenticate verifies user credentials and returns a JWT token.
+//
+// The token is valid for 24 hours and includes the user's ID and roles.
+//
+// Example:
+//
+//	token, err := Authenticate("user@example.com", "password")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	fmt.Println("Token:", token)
+//
+// Returns an error if credentials are invalid or database is unreachable.
+func Authenticate(email, password string) (string, error) {
+    // Implementation
+    return "", nil
+}
+```
+
+## Project Structure
+
+```
+project/
+├── go.mod              # Module definition
+├── go.sum              # Dependency checksums (commit this)
+├── README.md           # Project overview (allowed in root)
+├── CHANGELOG.md        # Version history (allowed in root)
+├── AGENTS.md          # AI assistant rules (allowed in root)
+├── LICENSE            # Project license (allowed in root)
+├── CONTRIBUTING.md    # Contribution guidelines (allowed in root)
+├── CODE_OF_CONDUCT.md # Code of conduct (allowed in root)
+├── SECURITY.md        # Security policy (allowed in root)
+├── cmd/
+│   └── myapp/
+│       └── main.go     # Application entry point
+├── internal/           # Private packages
+│   └── module/
+│       ├── module.go
+│       └── module_test.go
+├── pkg/                # Public packages
+│   └── api/
+│       ├── api.go
+│       └── api_test.go
+├── tests/              # Integration tests
+└── docs/               # Documentation
+```
+
+## Concurrency
+
+- Use goroutines for concurrent operations
+- Use channels for communication
+- Use `sync.WaitGroup` for synchronization
+- Use context for cancellation and timeouts
+- Avoid shared memory, prefer channels
+
+Example:
+```go
+func ProcessConcurrently(items []string) ([]Result, error) {
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    
+    results := make(chan Result, len(items))
+    errors := make(chan error, len(items))
+    
+    var wg sync.WaitGroup
+    for _, item := range items {
+        wg.Add(1)
+        go func(item string) {
+            defer wg.Done()
+            
+            select {
+            case <-ctx.Done():
+                errors <- ctx.Err()
+                return
+            default:
+                result, err := processItem(item)
+                if err != nil {
+                    errors <- err
+                    return
+                }
+                results <- result
+            }
+        }(item)
+    }
+    
+    wg.Wait()
+    close(results)
+    close(errors)
+    
+    // Collect results
+    var finalResults []Result
+    for r := range results {
+        finalResults = append(finalResults, r)
+    }
+    
+    // Check for errors
+    for err := range errors {
+        if err != nil {
+            return nil, err
+        }
+    }
+    
+    return finalResults, nil
+}
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows for:
+
+1. **Testing** (`go-test.yml`):
+   - Test on ubuntu-latest, windows-latest, macos-latest
+   - Test on Go 1.21, 1.22
+   - Upload coverage reports
+
+2. **Linting** (`go-lint.yml`):
+   - Format check: `gofmt -l .`
+   - Lint: `golangci-lint run`
+   - Vet: `go vet ./...`
+
+3. **Build** (`go-build.yml`):
+   - Build: `go build ./...`
+   - Verify binaries work
+
+## Module Publication
+
+### Publishing Go Modules
+
+Go modules are published via Git tags and automatically indexed by pkg.go.dev.
+
+**Prerequisites:**
+1. Public Git repository (GitHub, GitLab, etc.)
+2. Proper go.mod configuration
+3. Semantic versioning tags
+
+**go.mod Configuration:**
+
+```go
+module github.com/your-org/your-module
+
+go 1.22
+
+require (
+    github.com/example/dependency v1.2.3
+)
+```
+
+**Publishing Workflow:**
+
+1. Ensure go.mod is correct:
+   ```bash
+   go mod tidy
+   go mod verify
+   ```
+
+2. Run quality checks:
+   ```bash
+   go fmt ./...
+   go vet ./...
+   golangci-lint run
+   go test -v -race ./...
+   ```
+
+3. Create semantic version tag:
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+4. pkg.go.dev automatically indexes the module
+5. Verify at: `https://pkg.go.dev/github.com/your-org/your-module@v1.0.0`
+
+**Publishing Checklist:**
+
+- ✅ All tests passing (`go test ./...`)
+- ✅ No race conditions (`go test -race ./...`)
+- ✅ Code formatted (`go fmt ./...`)
+- ✅ No vet warnings (`go vet ./...`)
+- ✅ golangci-lint passes
+- ✅ go.mod is tidy (`go mod tidy`)
+- ✅ README.md with examples
+- ✅ LICENSE file present
+- ✅ Semantic version tag (v1.0.0)
+- ✅ CHANGELOG.md updated
+
+**Semantic Versioning:**
+
+Go uses semantic versioning strictly:
+
+- **v1.0.0** - First stable release
+- **v1.1.0** - New features (backwards compatible)
+- **v1.0.1** - Bug fixes
+- **v2.0.0** - Breaking changes (requires /v2 in module path)
+
+**Major Version Updates (v2+):**
+
+For v2 and above, update module path:
+
+```go
+// go.mod
+module github.com/your-org/your-module/v2
+
+go 1.22
+```
+
+**Module Documentation:**
+
+Write godoc-compatible comments:
+
+```go
+// Package yourmodule provides functionality for X, Y, and Z.
+//
+// Basic usage:
+//
+//	import "github.com/your-org/your-module"
+//
+//	result, err := yourmodule.Process("input")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+package yourmodule
+
+// Process handles the input and returns a result.
+//
+// Example:
+//
+//	result, err := Process("hello")
+//	if err != nil {
+//	    return err
+//	}
+//	fmt.Println(result)
+func Process(input string) (string, error) {
+    // Implementation
+}
+```
+
+**GOPROXY:**
+
+Go modules are automatically cached in public proxies:
+- https://proxy.golang.org (default)
+- https://goproxy.io
+- https://goproxy.cn
+
+No manual publication needed!
+
+**Retraction:**
+
+To retract a published version:
+
+```go
+// go.mod
+retract v1.0.5 // Critical bug in processing
+```
+
+<!-- GO:END -->
+