Contributors Guide

# Fork the repository on GitHub (click "Fork" button)

# Clone your fork
git clone https://github.com/YOUR_USERNAME/SAM.git
cd SAM

# Add upstream remote
git remote add upstream https://github.com/SyntheticAutonomicMind/SAM.git

# Initialize submodules
git submodule update --init --recursive

# Build SAM
make build-debug

# Run tests
make test

# Launch SAM
open .build/Build/Products/Debug/SAM.app

# Update main
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/my-new-feature

# Or for bug fixes:
git checkout -b fix/issue-123

git add .
git commit -m "type(scope): description

- Detail 1
- Detail 2

Fixes #123"

git commit -m "feat(tools): Add new web scraping tool"
git commit -m "fix(ui): Fix conversation list crash on delete"
git commit -m "docs: Update API reference for streaming"

# Push to your fork
git push origin feature/my-new-feature

# Create pull request on GitHub
# Visit: https://github.com/SyntheticAutonomicMind/SAM/compare

// ✅ Good: Clear, descriptive names
class ConversationManager { }
func sendMessage(to provider: AIProvider) { }
let maxTokenCount = 4096

// ❌ Bad: Ambiguous, abbreviated
class ConvMgr { }
func sndMsg(p: AIProv) { }
let mtc = 4096

// ✅ Good: Consistent spacing, clear structure
func processMessage(
    _ message: String,
    with context: [Message],
    tools: [Tool]?
) async throws -> Response {
    guard !message.isEmpty else {
        throw MessageError.empty
    }

    return try await provider.send(
        message,
        context: context,
        tools: tools
    )
}

// ❌ Bad: Inconsistent formatting
func processMessage(_  message:String,with context:[Message],tools:[Tool]?)async throws->Response{
    guard !message.isEmpty else{throw MessageError.empty}
    return try await provider.send(message,context:context,tools:tools)
}

// ✅ Good: Explain why, not what
// Cache results to avoid re-fetching from API
private var cache: [String: Result] = [:]

/// Sends a message to the AI provider with optional tool calling.
/// - Parameters:
///   - message: The user's message
///   - tools: Available tools for the model to use
/// - Returns: The AI's response
func sendMessage(_ message: String, tools: [Tool]?) async throws -> Response

// ❌ Bad: State the obvious
// This variable stores cache
private var cache: [String: Result] = [:]

// This function sends a message
func sendMessage(_ message: String, tools: [Tool]?) async throws -> Response

// ✅ Good: Specific, actionable errors
enum ToolError: LocalizedError {
    case invalidArguments(String)
    case executionFailed(String)
    case permissionDenied

    var errorDescription: String? {
        switch self {
        case .invalidArguments(let detail):
            return "Invalid tool arguments: \(detail)"
        case .executionFailed(let reason):
            return "Tool execution failed: \(reason)"
        case .permissionDenied:
            return "Permission denied to execute tool"
        }
    }
}

// ❌ Bad: Generic errors
enum ToolError: Error {
    case error
}

// ✅ Good: Modern concurrency
func fetchData() async throws -> Data {
    try await URLSession.shared.data(from: url).0
}

// ❌ Bad: Completion handlers (avoid when possible)
func fetchData(completion: @escaping (Result<Data, Error>) -> Void) {
    URLSession.shared.dataTask(with: url) { data, _, error in
        // ...
    }.resume()
}

// ✅ Good: Clear hierarchy, extracted subviews
struct ChatView: View {
    @StateObject private var viewModel: ChatViewModel

    var body: some View {
        VStack {
            MessageList(messages: viewModel.messages)
            InputField(text: $viewModel.input, onSend: viewModel.send)
        }
    }
}

// Extract complex views
struct MessageList: View {
    let messages: [Message]

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(messages) { message in
                    MessageRow(message: message)
                }
            }
        }
    }
}

// ✅ Good: Clear state ownership
@StateObject private var manager = ConversationManager()  // Owner
@ObservedObject var manager: ConversationManager         // Observer
@State private var isExpanded = false                    // Local state
@Environment(\.colorScheme) var colorScheme              // Environment

// ❌ Bad: Unclear ownership
@State var manager = ConversationManager()  // Creates new instance on every view update!

# Update your branch
git fetch upstream
git rebase upstream/main

# Run tests
make test

# Check for warnings
make build-debug

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
Describe how you tested the changes

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] Follows code style
- [ ] Commits follow conventions

Fixes #123

## Bug Description
Clear description of the bug

## Steps to Reproduce
1. Step 1
2. Step 2
3. Step 3

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- SAM version: 1.0.24
- macOS version: 14.2
- Hardware: M2 MacBook Pro

## Logs

## Screenshots
(if applicable)

## Feature Description
Clear description of the feature

## Use Case
Why is this feature needed?

## Proposed Solution
How would you implement it?

## Alternatives Considered
What other approaches did you consider?

## Additional Context
Any other relevant information

import XCTest
@testable import SAM

final class MyFeatureTests: XCTestCase {
    var sut: MyFeature!

    override func setUp() {
        super.setUp()
        sut = MyFeature()
    }

    func testFeatureBehavior() async throws {
        // Given
        let input = "test"

        // When
        let result = try await sut.process(input)

        // Then
        XCTAssertEqual(result, "expected")
    }
}

func testFullWorkflow() async throws {
    // Test complete feature workflow
    let provider = OpenAIProvider(apiKey: "test-key")
    let response = try await provider.sendMessage(
        "Hello",
        context: [],
        tools: nil,
        stream: false
    )

    XCTAssertFalse(response.content.isEmpty)
}

/// Sends a message to the AI provider.
///
/// This method handles:
/// - Message formatting
/// - Context management
/// - Tool calling
/// - Error handling
///
/// - Parameters:
///   - message: The user's input message
///   - context: Previous messages for context
///   - tools: Available tools the model can use
/// - Returns: The AI provider's response
/// - Throws: `ProviderError` if the request fails
func sendMessage(
    _ message: String,
    context: [Message],
    tools: [Tool]?
) async throws -> Response {
    // Implementation
}