fetch_ml/AGENTS.md

# AGENTS.md - Coding Agent Guidelines

This document provides essential information for agentic coding assistants working with the FetchML codebase.

## Build Commands

### Go Components
```bash
# Build all Go components
make build

# Build for development (faster compilation)
make dev

# Build for production (optimized)
make prod

# Cross-platform build for Linux/macOS/Windows
make cross-platform
```

### Zig CLI
```bash
# Build CLI with release-small optimization
cd cli && make all

# Build for development
cd cli && make dev

# Build for production
cd cli && make prod

# Alternative using zig build system
cd cli && zig build
```

## Test Commands

### Running Tests
```bash
# Run all tests
make test

# Run unit tests only
make test-unit

# Run integration tests only
make test-integration

# Run end-to-end tests only
make test-e2e

# Run with coverage report
make test-coverage

# Run a single test
go test -v ./path/to/package -run TestName

# Run tests with race detector
go test -race ./path/to/package/...
```

### Performance Testing
```bash
# Run performance benchmarks
make benchmark

# Run load testing suite
make load-test

# Run chaos engineering tests
make chaos-test

# Run complete technical excellence suite
make tech-excellence
```

## Lint Commands

```bash
# Run all linters and formatters
make lint

# Run Go linters
golangci-lint run

# Run Go formatters
gofmt -w ./cmd ./internal ./tests

# Run Go vet
go vet ./...

# Format Zig code
cd cli && zig fmt .

# Validate YAML configs against schema
make configlint
make worker-configlint
```

## Code Style Guidelines

### Go Code Style

1. **Formatting**:
   - Use `gofmt` for formatting
   - Line length: 100 characters (configured in .golangci.yml)
   - Use `goimports` for import organization

2. **Naming Conventions**:
   - Use camelCase for variables and functions
   - Use PascalCase for exported identifiers
   - Use clear, descriptive names
   - Acronyms should be all caps (e.g., HTTP, URL)

3. **Imports**:
   - Group imports in order: standard library, third-party, internal
   - Use meaningful import aliases when needed
   - Remove unused imports

4. **Error Handling**:
   - Always handle errors explicitly
   - Use `errors.Is` and `errors.As` for error checking
   - Wrap errors with context using `fmt.Errorf("context: %w", err)`

5. **Documentation**:
   - All exported functions, types, and variables must have doc comments
   - Comments should explain "why" not just "what"
   - Use godoc formatting conventions

### Zig Code Style

1. **Formatting**:
   - Use built-in Zig formatter (`zig fmt`)
   - Consistent indentation with 4 spaces

2. **Naming Conventions**:
   - Use camelCase for variables and functions
   - Use PascalCase for types
   - Use snake_case for file names

3. **Error Handling**:
   - Use Zig's error union types (`!T`)
   - Handle errors with `try`, `catch`, or `if` expressions
   - Return errors early when appropriate

### Python Code Style

1. **Formatting**:
   - Use Black formatter with 80 character line limit
   - Use isort for import organization (Google style)

2. **Type Checking**:
   - Use mypy with strict settings
   - All functions should have type annotations

3. **Testing**:
   - Use pytest framework
   - Follow naming conventions: `test_*` for functions, `*_test.py` for files

### YAML/Configuration Style

1. **Formatting**:
   - Use yamllint for validation
   - Consistent indentation with 2 spaces
   - No trailing whitespace

2. **Validation**:
   - All configs must pass schema validation
   - Use `make configlint` and `make worker-configlint`

## Development Guidelines

### Testing Requirements (from .windsurf/rules/test-new-features.md)
- Every new feature MUST include corresponding tests
- Test coverage for new code should be >80%
- Include both unit tests and integration tests where applicable
- Test edge cases, error paths, and boundary conditions

### Code Organization
- Clean up as you go - no orphaned files or dead code
- Remove commented-out code blocks
- Delete unused imports, functions, and variables immediately
- Consolidate duplicate code into reusable functions

### Documentation Standards
- Update relevant documentation IN THE SAME COMMIT as code changes
- Documentation locations:
  - README.md: User-facing features, installation, quick start
  - CHANGELOG.md: All changes, following Keep a Changelog format
  - Code comments: Complex logic, non-obvious decisions, API contracts
  - Function/struct docs: Public APIs must have doc comments

### Commit Message Convention
Use conventional commits:
- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation changes
- `style:` for formatting changes
- `refactor:` for code refactoring
- `test:` for adding/updating tests
- `chore:` for maintenance tasks

## Project Structure

- `cmd/` - Main applications
- `internal/` - Internal packages
- `cli/` - Zig command-line interface
- `tests/` - Test files organized by type
- `configs/` - Configuration files and schemas
- `docs/` - Documentation
- `scripts/` - Utility scripts

## Dependencies

- Go 1.25+
- Zig 0.15+
- Python 3.11+ (for some tools)
- Redis (for integration tests)
- Docker/Podman (for container-based tests)

## Useful Make Targets

```bash
# Development workflow
make dev-start     # Start development environment
make test          # Run all tests
make lint          # Run linters
make ci-local      # Run local CI dry-run

# Documentation
make docs          # Start documentation server
make docs-build    # Build static documentation

# Cleanup
make clean         # Remove build artifacts
make clean-docs    # Remove documentation artifacts
```