# Fjerkroa Bot Development Guide

This document outlines the development setup and workflows for the Fjerkroa Bot project.

## Development Tools Setup

### Prerequisites

- Python 3.11 (required - use `python3.11` and `pip3.11` explicitly)
- Git

### Quick Start

```bash
# Install development dependencies
make install-dev

# Or manually:
pip3.11 install -r requirements.txt
pip3.11 install -e .
pre-commit install
```

## Available Development Commands

Use the Makefile for all development tasks. Run `make help` to see all available commands:

### Installation
- `make install` - Install production dependencies
- `make install-dev` - Install development dependencies and pre-commit hooks

### Code Quality
- `make lint` - Run linter (flake8)
- `make format` - Format code with black and isort
- `make format-check` - Check if code is properly formatted
- `make type-check` - Run type checker (mypy)
- `make security-check` - Run security scanner (bandit)

### Testing
- `make test` - Run tests
- `make test-fast` - Run tests without slow tests
- `make test-cov` - Run tests with coverage report

### Combined Operations
- `make all-checks` - Run all code quality checks and tests
- `make pre-commit` - Run all pre-commit checks (format, then check)
- `make ci` - Full CI pipeline (install deps and run all checks)

### Utility
- `make clean` - Clean up temporary files and caches
- `make run` - Run the bot (requires config.toml)
- `make run-dev` - Run the bot in development mode with auto-reload

## Tool Configuration

All development tools are configured via `pyproject.toml` and `.flake8`:

### Code Formatting (Black + isort)
- Line length: 140 characters
- Target Python version: 3.8+
- Imports sorted and formatted consistently

### Linting (Flake8)
- Max line length: 140
- Max complexity: 10
- Ignores: E203, E266, E501, W503, E306 (for Black compatibility)

### Type Checking (MyPy)
- Strict type checking enabled
- Checks both `fjerkroa_bot` and `tests` directories
- Ignores missing imports for external libraries

### Security Scanning (Bandit)
- Scans for security issues
- Skips known safe patterns (pickle, random) for this application

### Testing (Pytest)
- Configured for async tests
- Coverage reporting available
- Markers for slow tests

## Pre-commit Hooks

Pre-commit hooks are automatically installed with `make install-dev`. They run:

1. Built-in checks (trailing whitespace, file endings, etc.)
2. Black code formatter
3. isort import sorter
4. Flake8 linter
5. Bandit security scanner
6. MyPy type checker
7. Fast tests

To run pre-commit manually:
```bash
pre-commit run --all-files
```

## Development Workflow

1. **Setup**: Run `make install-dev`
2. **Development**: Make your changes
3. **Check**: Run `make pre-commit` to format and check code
4. **Test**: Run `make test` or `make test-cov` for coverage
5. **Commit**: Git will automatically run pre-commit hooks

## Continuous Integration

The `make ci` command runs the complete CI pipeline:
- Installs all dependencies
- Runs linting (flake8)
- Checks formatting (black, isort)
- Runs type checking (mypy)
- Runs security scanning (bandit)
- Runs all tests

## File Structure

```
fjerkroa_bot/
├── fjerkroa_bot/           # Main package
├── tests/                  # Test files
├── requirements.txt        # Production dependencies
├── pyproject.toml         # Tool configuration
├── .flake8               # Flake8 configuration
├── .pre-commit-config.yaml # Pre-commit configuration
├── Makefile              # Development commands
└── setup.py              # Package setup
```

## Adding Dependencies

1. Add to `requirements.txt` for production dependencies
2. Add to `pyproject.toml` for development dependencies
3. Run `make install-dev` to install

## Troubleshooting

### Pre-commit Issues
```bash
# Reset pre-commit
pre-commit clean
pre-commit install
```

### Tool Not Found Errors
Ensure you're using `python3.11` and `pip3.11` explicitly, and that all dependencies are installed:
```bash
make install-dev
```

### Type Check Errors
Install missing type stubs:
```bash
pip3.11 install types-requests types-toml
```