dev-tools/README.md

# Development Tools

This directory contains local development infrastructure that mirrors the GitHub Actions CI/CD pipeline to prevent failures and improve development workflow.

## 🛠️ Available Tools

### `local-ci-check.sh`
Complete CI/CD pipeline simulation that runs all checks that GitHub Actions will perform:
- **Black formatting** check (88-character line length)
- **isort import sorting** check (black-compatible profile)
- **flake8 linting** (excludes E203/W503 for black compatibility)
- **pytest test suite** (runs all 45+ tests)
- **Git status check** (warns about uncommitted changes)

```bash
./dev-tools/local-ci-check.sh
```

### `format.sh`
Quick formatting utility that automatically fixes common formatting issues:
- Runs `black` to format code
- Runs `isort` to sort imports
- Checks `flake8` compliance after formatting

```bash
./dev-tools/format.sh
```

## 🚀 Makefile Commands

For convenience, all tools are also available through the root-level Makefile:

```bash
make help        # Show available commands
make format      # Quick format (uses format.sh)
make check       # Check formatting only
make test        # Run test suite only
make ci-check    # Full CI pipeline (uses local-ci-check.sh)
make install     # Install development dependencies
make clean       # Clean cache files
```

## ⚙️ Configuration Files

The development tools use these configuration files (located in project root):

- **`.flake8`**: Linting configuration with black-compatible settings
- **`pyproject.toml`**: Tool configurations for black, isort, and pytest
- **`Makefile`**: Convenient command aliases

## 🔄 Recommended Workflow

```bash
# 1. Make your changes
# 2. Format code
make format

# 3. Run full CI check
make ci-check

# 4. If everything passes, commit and push
git add .
git commit -m "Your commit message"
git push origin your-branch
```

## 🎯 Benefits

- **Prevent CI/CD failures** before pushing to GitHub
- **Consistent code quality** across all team members
- **Fast feedback loop** (~8 seconds for full check)
- **Team collaboration** through standardized development tools
- **Automated fixes** for common formatting issues

## 📝 Notes

- All tools respect the project's virtual environment (`./venv/`)
- Configuration matches GitHub Actions pre-commit hooks exactly
- Scripts provide helpful error messages and suggested fixes
- Designed to be run frequently during development